# Replace an over-mocked test with a contract test

A test that passes because the mocks agree with each other rather than with the real thing.

Category: Test coverage and flaky tests
Source: https://letsship.ai/use-cases/replace-an-over-mocked-test
Published: 2026-08-25

## Goal

Rewrite an over-mocked test so it asserts against the real shape of the dependency.

## Acceptance criteria

- The test validates against the dependency's real schema or a recorded response
- It fails when the real shape changes
- Mocks that only restate the implementation are removed
- The test still runs without network access

## What lands as proof

A demonstration that changing the real shape now breaks the test, which the mocked version did not do.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Replace the mocks in {test} with a contract test

Description: Rewrite an over-mocked test so it asserts against the real shape of the dependency.

Acceptance criteria:
- The test validates against the dependency's real schema or a recorded response
- It fails when the real shape changes
- Mocks that only restate the implementation are removed
- The test still runs without network access

Before you create the issue, find a test in this repository that mocks the thing it is meant to be testing and replace {test} with it.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: rewrite an over-mocked test so it asserts against the real shape of the dependency. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means the test fails when the real shape changes, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.