Тесты для сгенерированного кода: зафиксировать поведение до правок

npm init -y
npm pkg set type=module
npm install -D vitest@5.0.4 typescript@6.0.3 @types/node@24.19.2 \
  eslint@10.12.0 typescript-eslint@8.71.1 @vitest/eslint-plugin@1.6.27 husky@9.1.7

export type Role = "guest" | "client" | "manager" | "admin";
export type User = { id: string; role: Role };
export type OrderStatus = "new" | "paid" | "cancelled";
export type Order = { id: string; ownerId: string; status: OrderStatus; totalKzt: number };
export type Item = { priceKzt: number; qty: number };

const PROMOS: Record<string, number> = { WELCOME10: 10, VIP25: 25 };

export function calcTotal(items: Item[], promo?: string): number {
  const sum = items.reduce((acc, item) => acc + item.priceKzt * item.qty, 0);
  const percent = promo ? (PROMOS[promo.trim().toUpperCase()] ?? 0) : 0;
  return Math.round((sum * (100 - percent)) / 100);
}

export function canCancel(user: User, order: Order): boolean {
  if (order.status !== "new") return false;
  if (user.role === "admin" || user.role === "manager") return true;
  return user.role === "client" && user.id === order.ownerId;
}

import type { Order } from "./orders.js";

export interface PaymentGateway {
  charge(orderId: string, amountKzt: number, idempotencyKey: string): Promise<{ paymentId: string }>;
}

export type Deps = { orders: Map<string, Order>; gateway: PaymentGateway };

export async function payOrder(orderId: string, deps: Deps): Promise<Order> {
  const order = deps.orders.get(orderId);
  if (!order) throw new Error("ORDER_NOT_FOUND");
  if (order.status === "paid") return order;
  if (order.status !== "new") throw new Error("ORDER_NOT_PAYABLE");
  if (order.totalKzt <= 0) throw new Error("INVALID_AMOUNT");

  await deps.gateway.charge(order.id, order.totalKzt, `order-${order.id}`);
  const paid: Order = { ...order, status: "paid" };
  deps.orders.set(order.id, paid);
  return paid;
}

import { expect, it } from "vitest";
import { calcTotal } from "../../src/orders.js";

// Characterization test: records what calcTotal does today,
// including behaviour nobody has decided on yet.
it("calcTotal: current behaviour", () => {
  const cases = {
    "one item": calcTotal([{ priceKzt: 5000, qty: 1 }]),
    "two items": calcTotal([{ priceKzt: 5000, qty: 2 }, { priceKzt: 1500, qty: 1 }]),
    "empty cart": calcTotal([]),
    "promo WELCOME10": calcTotal([{ priceKzt: 5000, qty: 1 }], "WELCOME10"),
    "promo lower case + spaces": calcTotal([{ priceKzt: 5000, qty: 1 }], " vip25 "),
    "unknown promo": calcTotal([{ priceKzt: 5000, qty: 1 }], "FREE100"),
    "rounding 0.5": calcTotal([{ priceKzt: 5, qty: 1 }], "WELCOME10"),
    "negative qty": calcTotal([{ priceKzt: 5000, qty: -1 }]),
  };
  expect(cases).toMatchInlineSnapshot();
});

$ npx vitest run

 Snapshots  1 written
 Test Files  1 passed (1)
      Tests  1 passed (1)

import { expect, it } from "vitest";
import { calcTotal } from "../../src/orders.js";

// Characterization test: records what calcTotal does today,
// including behaviour nobody has decided on yet.
it("calcTotal: current behaviour", () => {
  const cases = {
    "one item": calcTotal([{ priceKzt: 5000, qty: 1 }]),
    "two items": calcTotal([{ priceKzt: 5000, qty: 2 }, { priceKzt: 1500, qty: 1 }]),
    "empty cart": calcTotal([]),
    "promo WELCOME10": calcTotal([{ priceKzt: 5000, qty: 1 }], "WELCOME10"),
    "promo lower case + spaces": calcTotal([{ priceKzt: 5000, qty: 1 }], " vip25 "),
    "unknown promo": calcTotal([{ priceKzt: 5000, qty: 1 }], "FREE100"),
    "rounding 0.5": calcTotal([{ priceKzt: 5, qty: 1 }], "WELCOME10"),
    "negative qty": calcTotal([{ priceKzt: 5000, qty: -1 }]),
  };
  expect(cases).toMatchInlineSnapshot(`
    {
      "empty cart": 0,
      "negative qty": -5000,
      "one item": 5000,
      "promo WELCOME10": 4500,
      "promo lower case + spaces": 3750,
      "rounding 0.5": 5,
      "two items": 11500,
      "unknown promo": 5000,
    }
  `);
});

$ CI=true npx vitest run

 FAIL  tests/characterization/calc-total.test.ts > calcTotal: current behaviour
Error: Snapshot `calcTotal: current behaviour 1` mismatched
 ❯ tests/characterization/calc-total.test.ts:17:17
     17|   expect(cases).toMatchInlineSnapshot();
       |                 ^

  Snapshots  1 failed
 Test Files  1 failed (1)

@@ -7,7 +7,7 @@ export type Item = { priceKzt: number; qty: number };
 const PROMOS: Record<string, number> = { WELCOME10: 10, VIP25: 25 };
 
 export function calcTotal(items: Item[], promo?: string): number {
-  const sum = items.reduce((acc, item) => acc + item.priceKzt * item.qty, 0);
+  const sum = items.reduce((acc, item) => acc + item.priceKzt * Math.max(0, item.qty), 0);
   const percent = promo ? (PROMOS[promo.trim().toUpperCase()] ?? 0) : 0;
   return Math.round((sum * (100 - percent)) / 100);
 }

$ npx vitest run tests/characterization

 FAIL  tests/characterization/calc-total.test.ts > calcTotal: current behaviour
Error: Snapshot `calcTotal: current behaviour 1` mismatched

- Expected
+ Received

@@ -1,8 +1,8 @@
  {
    "empty cart": 0,
-   "negative qty": -5000,
+   "negative qty": 0,
    "one item": 5000,

  Snapshots  1 failed
 Test Files  1 failed (1)

import { beforeEach, describe, expect, it, vi } from "vitest";
import type { Order } from "../../src/orders.js";
import { payOrder, type Deps } from "../../src/payments.js";

function setup(order: Order) {
  const charge = vi.fn(async () => ({ paymentId: "pay_test_1" }));
  const deps: Deps = { orders: new Map([[order.id, order]]), gateway: { charge } };
  return { deps, charge };
}

describe("payment of an order", () => {
  let order: Order;
  beforeEach(() => {
    order = { id: "o-1", ownerId: "u-1", status: "new", totalKzt: 4500 };
  });

  it("charges the exact total once and marks the order as paid", async () => {
    const { deps, charge } = setup(order);

    const paid = await payOrder("o-1", deps);

    expect(paid.status).toBe("paid");
    expect(charge).toHaveBeenCalledTimes(1);
    expect(charge).toHaveBeenCalledWith("o-1", 4500, "order-o-1");
  });

  it("a repeated payment does not charge the customer twice", async () => {
    const { deps, charge } = setup(order);

    await payOrder("o-1", deps);
    await payOrder("o-1", deps);

    expect(charge).toHaveBeenCalledTimes(1);
  });

  it("a cancelled order cannot be paid", async () => {
    const { deps, charge } = setup({ ...order, status: "cancelled" });

    await expect(payOrder("o-1", deps)).rejects.toThrow("ORDER_NOT_PAYABLE");
    expect(charge).not.toHaveBeenCalled();
  });

  it("an order with a zero or negative total is never sent to the gateway", async () => {
    const { deps, charge } = setup({ ...order, totalKzt: -5000 });

    await expect(payOrder("o-1", deps)).rejects.toThrow("INVALID_AMOUNT");
    expect(charge).not.toHaveBeenCalled();
  });

  it("the order stays unpaid if the gateway fails", async () => {
    const { deps, charge } = setup(order);
    charge.mockRejectedValueOnce(new Error("GATEWAY_TIMEOUT"));

    await expect(payOrder("o-1", deps)).rejects.toThrow("GATEWAY_TIMEOUT");
    expect(deps.orders.get("o-1")?.status).toBe("new");
  });
});

@@ -13,7 +13,11 @@ export async function payOrder(orderId: string, deps: Deps): Promise<Order> {
   if (order.status !== "new") throw new Error("ORDER_NOT_PAYABLE");
   if (order.totalKzt <= 0) throw new Error("INVALID_AMOUNT");
 
-  await deps.gateway.charge(order.id, order.totalKzt, `order-${order.id}`);
+  try {
+    await deps.gateway.charge(order.id, order.totalKzt, `order-${order.id}`);
+  } catch (error) {
+    console.warn("payment failed, will retry later", error);
+  }
   const paid: Order = { ...order, status: "paid" };
   deps.orders.set(order.id, paid);
   return paid;

$ npx vitest run tests/critical

 ❯ tests/critical/payment.test.ts (5 tests | 1 failed)
     × the order stays unpaid if the gateway fails

 FAIL  tests/critical/payment.test.ts > payment of an order > the order stays unpaid if the gateway fails
AssertionError: promise resolved "{ id: 'o-1', ownerId: 'u-1', …(2) }" instead of rejecting
+   "status": "paid",

 Test Files  1 failed | 1 passed (2)
      Tests  1 failed | 29 passed (30)

import { describe, expect, it } from "vitest";
import { canCancel, type Order, type OrderStatus, type Role } from "../../src/orders.js";

// The rule written out by hand, not derived from the code:
// only these combinations may cancel an order. Everything else is forbidden.
const ALLOWED = new Set([
  "client/own/new",
  "manager/own/new",
  "manager/foreign/new",
  "admin/own/new",
  "admin/foreign/new",
]);

const roles: Role[] = ["guest", "client", "manager", "admin"];
const statuses: OrderStatus[] = ["new", "paid", "cancelled"];
const matrix = roles.flatMap((role) =>
  (["own", "foreign"] as const).flatMap((owner) =>
    statuses.map((status) => ({ role, owner, status, allowed: ALLOWED.has(`${role}/${owner}/${status}`) })),
  ),
);

describe("who can cancel an order", () => {
  it("the matrix covers every combination", () => {
    expect(matrix).toHaveLength(roles.length * 2 * statuses.length);
  });

  it.each(matrix)("$role, $owner order, $status → $allowed", ({ role, owner, status, allowed }) => {
    const order: Order = { id: "o-1", ownerId: "u-1", status, totalKzt: 5000 };
    const user = { id: owner === "own" ? "u-1" : "u-2", role };
    expect(canCancel(user, order)).toBe(allowed);
  });
});

@@ -13,7 +13,5 @@ export function calcTotal(items: Item[], promo?: string): number {
 }
 
 export function canCancel(user: User, order: Order): boolean {
-  if (order.status !== "new") return false;
-  if (user.role === "admin" || user.role === "manager") return true;
-  return user.role === "client" && user.id === order.ownerId;
+  return order.status === "new" && user.role !== "guest";
 }

$ npx vitest run tests/critical

 ❯ tests/critical/permissions.test.ts (25 tests | 1 failed)
   ❯ who can cancel an order (25)
     × client, foreign order, new → false

 FAIL  tests/critical/permissions.test.ts > who can cancel an order > client, foreign order, new → false
AssertionError: expected true to be false // Object.is equality

 Test Files  1 failed | 1 passed (2)
      Tests  1 failed | 29 passed (30)

@@ -25,12 +25,10 @@ describe("payment of an order", () => {
   });
 
   it("a repeated payment does not charge the customer twice", async () => {
-    const { deps, charge } = setup(order);
+    const { deps } = setup(order);
 
     await payOrder("o-1", deps);
     await payOrder("o-1", deps);
-
-    expect(charge).toHaveBeenCalledTimes(1);
   });
 
   it("a cancelled order cannot be paid", async () => {
@@ -47,7 +45,7 @@ describe("payment of an order", () => {
     expect(charge).not.toHaveBeenCalled();
   });
 
-  it("the order stays unpaid if the gateway fails", async () => {
+  it.skip("the order stays unpaid if the gateway fails", async () => {
     const { deps, charge } = setup(order);
     charge.mockRejectedValueOnce(new Error("GATEWAY_TIMEOUT"));

$ npm test
 Test Files  3 passed (3)
      Tests  30 passed | 1 skipped (31)

$ npm run lint
tests/critical/payment.test.ts
  27:3  error  Test has no assertions                                                       vitest/expect-expect
  48:6  error  Disabled test - if you want to skip a test temporarily, use .todo() instead  vitest/no-disabled-tests

✖ 2 problems (2 errors, 0 warnings)

import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import vitest from "@vitest/eslint-plugin";

export default defineConfig(
  tseslint.configs.recommended,
  {
    files: ["tests/**/*.ts"],
    plugins: { vitest },
    rules: {
      ...vitest.configs.recommended.rules,
      // a skipped or focused test must not reach the main branch
      "vitest/no-disabled-tests": "error",
      "vitest/no-focused-tests": "error",
      // a test without a single expect proves nothing
      "vitest/expect-expect": "error",
    },
  },
);

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    include: ["tests/**/*.test.ts"],
    allowOnly: false,
  },
});

$ npx vitest run
 FAIL  tests/critical/payment.test.ts > payment of an order > a cancelled order cannot be paid
Error: [Vitest] Unexpected .only modifier. Remove it or pass --allowOnly argument to bypass this error
 Test Files  1 failed | 2 passed (3)

# AGENTS.md

## Tests

- Run `npm run check` before reporting a task as done and show the output.
- For a bug, first write a test that fails, then fix the code.
- Tests in `tests/critical/` describe payment and access rules.
  Do not edit, skip or delete them without asking.
- A failing snapshot means behaviour changed. Report the diff;
  never run `vitest -u` to make the run green.
- Never add `.skip`, `.only` or remove `expect` calls to pass a check.

# Payment and access rules need a human review
/tests/critical/ @your-org/maintainers
/tests/characterization/ @your-org/maintainers

{
  "scripts": {
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "check": "npm run typecheck && npm run lint && npm test",
    "prepare": "husky"
  }
}

npm run check

$ git commit -m "Simplify canCancel"
> vitest run
 ❯ tests/critical/permissions.test.ts (25 tests | 1 failed)
     × client, foreign order, new → false
 Test Files  1 failed | 2 passed (3)
      Tests  1 failed | 30 passed (31)
husky - pre-commit script failed (code 1)
exit code: 1

$ git commit --no-verify -m "Simplify canCancel"
[main 48bc214] Simplify canCancel
 1 file changed, 1 insertion(+), 3 deletions(-)
exit code: 0

name: check

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run check

$ docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.12 -verbose .github/workflows/check.yml
verbose: Found 0 parse errors in 0 ms for .github/workflows/check.yml
verbose: Found total 0 errors in 22 ms for .github/workflows/check.yml