Build it

Write the unit tests for priceOrder with a builder and boundary tables, then API tests for POST /orders against a real PostgreSQL. The code is TypeScript in a NestJS project with Vitest, as in From script to service: a small API in Node; you need Docker running for the API tests.

1. Keep the price rules in one pure function

   TypeScriptCopy

   // src/pricing/price-order.ts: all money in integer cents
   export type PricedLine = { articleId: string; priceCents: number; qty: number };
   export type PriceInput = { lines: PricedLine[]; code: string | null; firstOrder: boolean; staff: boolean };
   export type Price = { subtotalCents: number; discountCents: number; deliveryFeeCents: number; totalCents: number };
   
   export function priceOrder({ lines, code, firstOrder, staff }: PriceInput): Price {
     for (const line of lines) {
       if (!Number.isInteger(line.qty) || line.qty < 1 || line.qty > 20) throw new RangeError('qty must be 1 to 20');
     }
     const subtotalCents = lines.reduce((sum, l) => sum + l.priceCents * l.qty, 0);
     if (subtotalCents < 500 || subtotalCents > 50_000) throw new RangeError('cart must be 500 to 50000 cents');
   
     let discountCents = 0;
     if (staff) {
       discountCents = Math.floor((subtotalCents * 5) / 100);           // staff: 5%, never with FRESH10
     } else if (code === 'FRESH10' && firstOrder && subtotalCents >= 2_000) {
       discountCents = Math.floor(subtotalCents / 10);                  // 10% from $20, first order only
     }
     const deliveryFeeCents = subtotalCents >= 2_500 ? 0 : 150;         // based on the subtotal before discounts
     return { subtotalCents, discountCents, deliveryFeeCents, totalCents: subtotalCents - discountCents + deliveryFeeCents };
   }

   Discounts round down to whole cents, and the delivery fee looks at the subtotal before discounts. Those are product decisions; write them in a comment so the tests and the code agree on purpose.

2. Add a builder and a factory for test data

   test/builders/order.builder.tstest/builders/order-body.ts

   TypeScriptCopy

   // test/builders/order.builder.ts: fresh, valid price input for every test
   import type { PriceInput, PricedLine } from '../../src/pricing/price-order.js';
   
   export function anOrder() {
     const order: PriceInput = {                                     // a new object on every call
       lines: [{ articleId: 'A1001', priceCents: 1_250, qty: 2 }],   // a plain $25 cart
       code: null, firstOrder: false, staff: false,
     };
     const builder = {
       withLines(...lines: PricedLine[]) { order.lines = lines.map((l) => ({ ...l })); return builder; },
       withSubtotal(cents: number) { return builder.withLines({ articleId: 'A1001', priceCents: cents, qty: 1 }); },
       withCode(code: string) { order.code = code; return builder; },
       asFirstOrder() { order.firstOrder = true; return builder; },
       asStaff() { order.staff = true; return builder; },
       build(): PriceInput { return { ...order, lines: order.lines.map((l) => ({ ...l })) }; },  // copy nested lines too
     };
     return builder;
   }

3. Write the unit tests as boundary tables

   TypeScriptCopy

   // src/pricing/price-order.spec.ts
   import { describe, it, expect } from 'vitest';
   import { priceOrder } from './price-order.js';
   import { anOrder } from '../../test/builders/order.builder.js';
   
   describe('priceOrder', () => {
     it.each([
       { subtotal: 2_499, fee: 150 },
       { subtotal: 2_500, fee: 0 },
     ])('charges $fee cents delivery on a $subtotal cent cart', ({ subtotal, fee }) => {
       const order = anOrder().withSubtotal(subtotal).build();         // arrange
       const price = priceOrder(order);                                // act
       expect(price.deliveryFeeCents).toBe(fee);                       // assert
     });
   
     it.each([
       { subtotal: 1_999, discount: 0 },
       { subtotal: 2_000, discount: 200 },
     ])('gives a first order $discount cents off a $subtotal cent cart with FRESH10', ({ subtotal, discount }) => {
       const order = anOrder().withSubtotal(subtotal).asFirstOrder().withCode('FRESH10').build();
       expect(priceOrder(order).discountCents).toBe(discount);
     });
   
     it('gives no FRESH10 discount on a second order', () => {
       expect(priceOrder(anOrder().withSubtotal(3_000).withCode('FRESH10').build()).discountCents).toBe(0);
     });
   
     it('gives staff only their 5% when they also enter FRESH10', () => {
       const order = anOrder().withSubtotal(3_000).asStaff().asFirstOrder().withCode('FRESH10').build();
       expect(priceOrder(order).discountCents).toBe(150);
     });
   
     it.each([500, 50_000])('accepts a %i cent cart', (subtotal) => {
       expect(priceOrder(anOrder().withSubtotal(subtotal).build()).subtotalCents).toBe(subtotal);
     });
   
     it.each([499, 50_001])('rejects a %i cent cart', (subtotal) => {
       expect(() => priceOrder(anOrder().withSubtotal(subtotal).build())).toThrow(RangeError);
     });
   
     it.each([0, 21])('rejects a line with qty %i', (qty) => {
       const order = anOrder().withLines({ articleId: 'A1001', priceCents: 1_000, qty }).build();
       expect(() => priceOrder(order)).toThrow('qty must be 1 to 20');
     });
   });

   Run npx vitest run src/pricing. Each table row is reported as its own test with its values in the name, and the whole file runs in well under a second. To prove the tables have teeth, change >= 2_500 to > 2_500 in priceOrder: exactly one row, the 2,500 cent cart, goes red. Change it back.

4. Start one real PostgreSQL for the whole run

   Install the module with npm install -D @testcontainers/postgresql pg @types/pg. The image name is required; pin the major version you run in production.

   test/global-setup.tsvitest.config.api.ts

   TypeScriptCopy

   // test/global-setup.ts: runs once, before any API test file
   import { PostgreSqlContainer } from '@testcontainers/postgresql';
   import type { TestProject } from 'vitest/node';
   import { runMigrations, seedReferenceData } from '../src/db/migrate.js';
   
   export default async function setup(project: TestProject) {
     const container = await new PostgreSqlContainer('postgres:16-alpine').start();
     const url = container.getConnectionUri();
     await runMigrations(url);           // the same migrations production runs
     await seedReferenceData(url);       // articles and SLOT-TEST: read-only, shared by all tests
     project.provide('databaseUrl', url);
     return async () => { await container.stop(); };   // teardown after the last file
   }
   
   declare module 'vitest' {
     export interface ProvidedContext { databaseUrl: string }
   }

   Global setup runs in its own scope, so it cannot share variables with tests. provide passes the connection string, and tests read it with inject('databaseUrl').

5. Boot the app once per file, with a fake payment gateway

   TypeScriptCopy

   // test/orders.api-spec.ts (part 1): setup and helpers
   import { Test } from '@nestjs/testing';
   import type { INestApplication } from '@nestjs/common';
   import request from 'supertest';
   import type { App } from 'supertest/types.js';
   import { randomUUID } from 'node:crypto';
   import { Pool } from 'pg';
   import { inject } from 'vitest';
   import { AppModule } from '../src/app.module.js';
   import { setupApp } from '../src/setup.js';
   import { AuthService } from '../src/auth/auth.service.js';
   import { PaymentGateway } from '../src/payments/payment.gateway.js';
   import { FakePaymentGateway } from './fakes/fake-payment.gateway.js';
   import { orderBody } from './builders/order-body.js';
   
   let app: INestApplication<App>;
   let db: Pool;
   const payments = new FakePaymentGateway();       // keeps charges in a list; can decline the next one
   
   beforeAll(async () => {
     process.env.DATABASE_URL = inject('databaseUrl');
     const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
       .overrideProvider(PaymentGateway).useValue(payments)   // no real card or wallet network
       .compile();
     app = moduleRef.createNestApplication();
     setupApp(app);                                  // the same validation pipes as production
     await app.init();
     db = new Pool({ connectionString: inject('databaseUrl') });
   });
   afterAll(async () => { await app.close(); await db.end(); });
   
   async function newCustomer() {                   // unique per test: safe when files run in parallel
     const id = randomUUID();
     await db.query('INSERT INTO customer (id, email) VALUES ($1, $2)', [id, `t-${id}@example.test`]);
     return { id, auth: { Authorization: `Bearer ${app.get(AuthService).tokenFor(id)}` } };
   }
   const ordersOf = async (customerId: string) =>
     (await db.query('SELECT id, total_cents FROM "order" WHERE customer_id = $1', [customerId])).rows;
   const post = (auth: object, body: object, key: string = randomUUID()) =>
     request(app.getHttpServer()).post('/orders').set(auth).set('Idempotency-Key', key).send(body);

   "order" needs quotes in SQL because ORDER is a keyword. AuthService.tokenFor is the app's own token signer, so the test signs in the same way the app checks; the secret comes from the test environment.

6. Test the happy path, the negatives and the double submit

   TypeScriptCopy

   // test/orders.api-spec.ts (part 2): status, body and side effects
   describe('POST /orders', () => {
     it('stores a placed order and charges the card once', async () => {
       const c = await newCustomer();
       const res = await post(c.auth, orderBody()).expect(201);              // 2 x 1,250 = 2,500
       expect(res.body).toMatchObject({ status: 'placed', totalCents: 2_500, deliveryFeeCents: 0 });
       expect(await ordersOf(c.id)).toEqual([{ id: res.body.id, total_cents: 2_500 }]);
       expect(payments.chargesFor(res.body.id)).toEqual([{ amountCents: 2_500 }]);
     });
   
     it('rejects qty 21 with 400 and stores nothing', async () => {
       const c = await newCustomer();
       await post(c.auth, orderBody({ lines: [{ articleId: 'A1001', qty: 21 }] })).expect(400);
       expect(await ordersOf(c.id)).toEqual([]);
     });
   
     it('rejects a 350 cent cart with 422 and stores nothing', async () => {
       const c = await newCustomer();
       await post(c.auth, orderBody({ lines: [{ articleId: 'A3010', qty: 1 }] })).expect(422);
       expect(await ordersOf(c.id)).toEqual([]);
     });
   
     it('turns a double submit with the same key into one order and one charge', async () => {
       const c = await newCustomer();
       const key = randomUUID();
       const [first, second] = await Promise.all([post(c.auth, orderBody(), key), post(c.auth, orderBody(), key)]);
       const ok = [first, second].filter((r) => r.status === 201);
       expect(ok.length).toBeGreaterThan(0);                                // the other may be a 409 while the first runs
       expect(await ordersOf(c.id)).toHaveLength(1);
       const retry = await post(c.auth, orderBody(), key).expect(201);      // a later retry replays the first result
       expect(retry.body.id).toBe(ok[0].body.id);
       expect(payments.chargesFor(retry.body.id)).toHaveLength(1);
     });
   
     it('rejects the same key with a different body with 422', async () => {
       const c = await newCustomer();
       const key = randomUUID();
       await post(c.auth, orderBody(), key).expect(201);
       await post(c.auth, orderBody({ paymentMethod: 'cod' }), key).expect(422);
       expect(await ordersOf(c.id)).toHaveLength(1);
     });
   });

   Run npx vitest run --config ./vitest.config.api.ts. The first run pulls the PostgreSQL image, which takes a while; after that, the container starts in a few seconds and each test takes tens to a few hundred milliseconds. Add the API run to CI next to the unit tests; Stable suites in CI splits them into jobs.