<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for DeepSeek: scripts/model-profiles.json -->

#Task boundary

1. Implement exactly the task as stated. Do not add abstractions, options, config, or files the task did not name.
2. Comments, identifiers, commit messages and log strings are English only.
3. Stop when the checklist at the end passes. Do not refactor or "improve" surrounding code.
4. Every checklist item below is backed by an assertion in a test or by pasted command output, never by a sentence.

---

#Purpose

Rules for tests that exercise more than one component together — your code plus a real database, a real HTTP layer, a real queue.

Integration tests exist to catch what unit tests structurally cannot: wrong SQL, a missing migration, a serialisation mismatch, a transaction that does not roll back, middleware ordering. Every one of those bugs passes a suite of green unit tests, because the mock agreed with the misunderstanding.

---

#Use the real dependency

Run the actual database, not an in-memory substitute.

js
// SQLite standing in for Postgres will not catch: JSONB operators, array
// columns, `ON CONFLICT` semantics, partial indexes, or citext behaviour.
const container = await new PostgreSqlContainer("postgres:16").start();
process.env.DATABASE_URL = container.getConnectionUri();
await migrate();                       // run real migrations, not a schema dump

1. Use Testcontainers, Docker Compose, or a dedicated test instance. Pin the same major version as production.
2. Run the real migrations in the test setup. This is how you learn that migration 47 fails on a table with data — a class of failure no other test catches.
3. Never substitute SQLite for Postgres or MySQL. The dialects differ where bugs live.

---

#Isolation

Tests must not see each other's data, and must be safe to run in parallel.

js
afterEach(async () => {
  // Truncate every table in one statement; RESTART IDENTITY keeps ids stable
  await db.$executeRawUnsafe(`
    TRUNCATE TABLE ${tables.join(", ")} RESTART IDENTITY CASCADE
  `);
});

Never rely on tests running in a particular order, and never let one test depend on data another created. Each test builds what it needs.

Prefer factories over shared fixtures — a function that creates a valid record with sensible defaults and accepts overrides. A fixture file that every test reads becomes a coupling point nobody dares change.

---

#Third parties

Do not call real external APIs from tests. They are slow, rate-limited, and turn an unrelated outage into a red build.

Record real responses once and replay them, so the fake reflects what the provider actually returns rather than what the documentation claims:

js
server.use(
  http.post("https://api.stripe.com/v1/charges", () =>
    HttpResponse.json(recordedChargeResponse, { status: 200 })
  )
);

Always fake the failure modes too — timeout, 429, 500, malformed body, partial response. Untested error paths are where integration bugs hide, and the happy path is the one part unit tests already covered.

---

#Tooling

Transaction-rollback isolation in practice: open a transaction in beforeEach, hand the transaction-scoped client to the code under test, and ROLLBACK in afterEach. It is the fastest strategy, but it breaks the moment the code under test issues its own BEGIN/COMMIT, or relies on pg_notify, advisory locks, or a connection pool that hands out a second connection. When that happens, fall back to TRUNCATE rather than fighting it.

#What to test at this level

Test the API through its real HTTP surface, not by calling handlers directly:

js
const res = await request(app)
  .get("/api/invoices/inv_44c")
  .set("Authorization", `Bearer ${tokenForOtherTenant}`);

expect(res.status).toBe(404);          // not 403 — see Security/authorization

That test catches middleware ordering, serialisation and authorisation together — none of which a direct handler call exercises.

---

#Keeping them fast

Integration tests are slower by nature; keep them from becoming the reason nobody runs the suite.

1. Start containers once per run, not per test file. Reuse across the suite.
2. Parallelise by worker with a schema or database each.
3. Seed the minimum needed. A 500-row fixture where 2 rows suffice costs on every test.
4. Keep the ratio sane: many unit tests, a meaningful layer of integration tests, a handful of end-to-end tests. Inverting that produces a suite that takes 40 minutes and gets skipped.
5. Run them on every pull request, not nightly. A failure found a day later has already been built on.

---

#Anti-patterns

---

#Checklist

• Tests run against the same database engine and major version as production
• Real migrations are applied in setup, not a schema dump
• Each test is isolated by transaction, truncation, or per-worker schema
• No test depends on another's data or on execution order
• Test data comes from factories with overrides, not shared fixtures
• No real external API is called; fakes intercept at the HTTP boundary
• Failure modes are faked as well as success
• The API is exercised through its real HTTP surface
• Cross-tenant authorisation is covered with two tenants
• Containers start once per run and tests parallelise by worker
• The suite runs on every pull request