Reactive-Resume/plans/001-resume-service-characterization-tests.md

Plan 001: Characterization tests for the resume service

Executor instructions: Follow this plan step by step. Run every verification command and confirm the expected result before moving to the next step. If anything in the "STOP conditions" section occurs, stop and report — do not improvise. When done, update the status row for this plan in plans/README.md.

Drift check (run first): git diff --stat 73daf22b2..HEAD -- packages/api/src/features/resume/service.ts If service.ts changed since this plan was written, compare the "Current state" excerpts against the live code before proceeding; on a mismatch, treat it as a STOP condition.

Status

• Priority: P1
• Effort: M
• Risk: LOW
• Depends on: none
• Category: tests
• Planned at: commit 73daf22b2, 2026-07-08

Why this matters

packages/api/src/features/resume/service.ts is 772 lines and owns every resume mutation — create, update, patch (JSON Patch application), delete, duplicate, setLocked, setPassword, removePassword, verifyPassword, getBySlug, plus version-history snapshotting. It has no service.test.ts. The only coverage is Playwright e2e, which exercises the happy path through the UI and cannot assert error codes, lock enforcement, or snapshot throttling in isolation. This service also has high churn (v5.2.0 added undo/redo + version history). Characterization tests here (a) catch regressions in CRUD/patch/lock/password behavior before users do, and (b) are a prerequisite for Plan 003 (which changes not-found behavior in this file) and Plan 007 (template refactor) — you cannot safely refactor code that has no behavioral net under it.

The goal is characterization tests: capture what the code does today, locking in current behavior so later changes are deliberate, not accidental.

Current state

• packages/api/src/features/resume/service.ts — the service under test. Exports a resumeService object literal whose methods each take an input object and call the mocked db. Key behaviors to pin down:

  • update (lines ~555–635): reads isLocked; throws ORPCError("RESUME_LOCKED") if locked; on a successful UPDATE ... RETURNING, if !resume throws ORPCError("NOT_FOUND"); maps a unique-constraint violation on resume_slug_user_id_unique to ORPCError("RESUME_SLUG_ALREADY_EXISTS").
  • setLocked (lines ~663–679), setPassword (~681–699), removePassword (~726–742): each runs an UPDATE ... RETURNING, then if (!resume) return; (silent no-op when no row matches — this is today's behavior; capture it as-is. Plan 003 will change it.), else calls notifyResumeUpdated.
  • delete (lines ~744–769): transaction that throws NOT_FOUND when the row is missing and RESUME_LOCKED when locked, then deletes and cleans storage.
  • statistics.increment (lines ~199–237): two INSERT ... ON CONFLICT DO UPDATE writes inside a transaction.

• Test convention to follow — model the new test after the existing sibling packages/api/src/features/applications/service.test.ts. It mocks the DB layer with vi.hoisted + vi.mock, then dynamically imports the service. The exact shape to copy (from that file, lines 1–68):

  import { beforeEach, describe, expect, it, vi } from "vitest";
  
  const dbMock = vi.hoisted(() => ({
    select: vi.fn(), insert: vi.fn(), update: vi.fn(),
    delete: vi.fn(), transaction: vi.fn(),
  }));
  vi.mock("@reactive-resume/db/client", () => ({ db: dbMock }));
  vi.mock("@reactive-resume/db/schema", () => ({ /* stub the tables used */ }));
  vi.mock("drizzle-orm", () => ({
    and: (...a: unknown[]) => a, eq: (...a: unknown[]) => a,
    isNotNull: (...a: unknown[]) => a, sql: Object.assign(
      (s: TemplateStringsArray, ...v: unknown[]) => ({ s, v }),
      { join: (v: unknown[]) => v },
    ),
  }));
  
  const { resumeService } = await import("./service");
  

  Note the applications/service.test.ts helpers createSelectChain(rows) and setSelectResults(...) — reuse that pattern to script what each db.select / db.update().returning() call resolves to.

• Mocks this service needs beyond the applications example (grep the imports at the top of service.ts and mock each):

  • bcrypt (hash, compare) — used by setPassword/verifyPassword. (The real import specifier in service.ts is bcrypt, not bcryptjs — mock that exact module path.) Mock hash to return a fixed string and compare to return a boolean you control.
  • The snapshot/patch helpers imported into service.ts (e.g. applyResumePatchTx, maybeSnapshotOnSave, writeResumeVersion, notifyResumeUpdated, getStorageService) — mock them so the service's own branching is what's under test, not their internals. Read the top of service.ts to get the exact import specifiers and mock each module path the same way the applications test mocks ../storage/service.

• ORPCError assertions — errors are ORPCError instances from @orpc/server with a .code (e.g. "NOT_FOUND", "RESUME_LOCKED"). Assert with await expect(fn()).rejects.toThrow() and, where you can, check the code: await fn().catch((e) => expect(e.code).toBe("RESUME_LOCKED")), or assert on .message. Confirm the real shape by reading how access-policy.test.ts or access.test.ts in the same folder assert on ORPCError and copy that style.

Commands you will need

Purpose	Command	Expected on success
Typecheck	pnpm --filter @reactive-resume/api typecheck	exit 0, no errors
Run test	pnpm --filter @reactive-resume/api test -- resume/service.test.ts	all pass
All api tests	pnpm --filter @reactive-resume/api test	all pass

(These are the repo's real commands — package-scoped Vitest via Turborepo. Do NOT run pnpm check; it rewrites files.)

Scope

In scope (the only files you should create/modify):

• packages/api/src/features/resume/service.test.ts (create)
• plans/README.md (status row only)

Out of scope (do NOT touch):

• packages/api/src/features/resume/service.ts — this plan adds tests that characterize its current behavior. Do not "fix" anything you find here, even the silent if (!resume) return; no-ops in setLocked/setPassword/ removePassword — those are Plan 003's job, and this test must assert the current silent-return behavior so Plan 003's change is visible as a test diff.
• Any router file (crud.ts, sharing.ts) — router tests are a separate future effort.
• The real database or migrations — this is a pure unit test with a mocked db.

Git workflow

• Branch: advisor/001-resume-service-tests
• Commit style: conventional commits (repo uses them — e.g. test(api): add characterization tests for resume service).
• Do NOT push or open a PR unless the operator instructed it.

Steps

Step 1: Scaffold the test file and mocks

Create packages/api/src/features/resume/service.test.ts. Copy the mock scaffolding pattern from applications/service.test.ts (lines 1–68). Read the top-of-file imports in service.ts and add a vi.mock(...) for every module it imports that touches I/O (db, schema, drizzle-orm, bcryptjs, storage service, and the patch/snapshot/notify helpers). Stub @reactive-resume/db/schema with the table/column objects the service references (resume, resumeStatistics, resumeStatisticsDaily, user).

Verify: pnpm --filter @reactive-resume/api test -- resume/service.test.ts → the file is picked up (even with zero real tests it should not error on import; add one it("imports", () => expect(resumeService).toBeDefined()) to confirm wiring). Expected: 1 passing test.

Step 2: Characterize update

Add a describe("update") block with these cases, asserting current behavior:

• Throws RESUME_LOCKED when the pre-read returns { isLocked: true }.
• Returns the updated row on success (script db.update().set().where().returning() to resolve [{ id, name, slug, ... }]).
• Throws NOT_FOUND when the RETURNING resolves to [] (no row matched).
• Maps a thrown error whose cause.constraint === "resume_slug_user_id_unique" to RESUME_SLUG_ALREADY_EXISTS.

Verify: pnpm --filter @reactive-resume/api test -- resume/service.test.ts → all cases pass.

Step 3: Characterize setLocked, setPassword, removePassword

Add a describe for each. For every method assert both paths:

• Success path: RETURNING resolves to [{ id, updatedAt }] → the method resolves (returns undefined) and notifyResumeUpdated was called once with the expected mutation value ("lock" / "password").
• Not-found path: RETURNING resolves to [] → the method resolves undefined and notifyResumeUpdated is NOT called (this pins the current silent no-op; Plan 003 will flip this to throwing NOT_FOUND).
• For setPassword, assert hash (mocked bcrypt) was called with the input password before the update.

Verify: pnpm --filter @reactive-resume/api test -- resume/service.test.ts → all pass.

Step 4: Characterize verifyPassword and delete

• verifyPassword: throws INVALID_PASSWORD when no matching row; throws INVALID_PASSWORD when compare (mocked) returns false; returns true and calls grantResumeAccess when compare returns true.
• delete: script the transaction mock (see how applications/service.test.ts handles db.transaction — if it doesn't, make dbMock.transaction invoke its callback with a tx object exposing the same select/delete chain). Assert NOT_FOUND when the row is missing, RESUME_LOCKED when locked, and storage delete called for both screenshot and pdf keys on success.

Verify: pnpm --filter @reactive-resume/api test -- resume/service.test.ts → all pass.

Step 5: Characterize statistics.increment

Assert that a views: true call runs db.transaction, and inside it inserts into both resumeStatistics and resumeStatisticsDaily with an onConflictDoUpdate. You do not need to assert SQL text — assert that both tx.insert(...) calls happen (spy on the tx insert). This case is the safety net for Plan 005, which changes when increment is called (not its body).

Verify: pnpm --filter @reactive-resume/api test → the whole api package test suite passes (no regressions in sibling tests from your new mocks).

Test plan

• New file: packages/api/src/features/resume/service.test.ts, structured as one describe per method, following applications/service.test.ts as the structural pattern.
• Cases per method are listed in Steps 2–5 (happy path + each error/edge branch the code contains today).
• Verification: pnpm --filter @reactive-resume/api test → all pass, including the new tests. Count the new tests in the output; expect ≥ 14 new cases.

Done criteria

Machine-checkable. ALL must hold:

• packages/api/src/features/resume/service.test.ts exists
• pnpm --filter @reactive-resume/api test -- resume/service.test.ts exits 0 with ≥ 14 passing cases
• pnpm --filter @reactive-resume/api test exits 0 (no sibling regressions)
• pnpm --filter @reactive-resume/api typecheck exits 0
• git status --porcelain shows only service.test.ts (new) and plans/README.md modified
• plans/README.md status row for 001 updated to DONE

STOP conditions

Stop and report back (do not improvise) if:

• service.ts has drifted from the excerpts above (method line ranges or error codes differ materially) — the codebase changed since this plan was written.
• The mocking approach fights the service: e.g. the service imports something that runs real I/O at module load and can't be cleanly mocked. Report what and where; do not weaken the test into a no-op.
• You find a genuine bug while characterizing (behavior that looks wrong). Do NOT fix it here — write the test to capture current behavior, add a // NOTE: characterizes current behavior; see finding comment, and report it.

Maintenance notes

• Plan 003 changes setLocked/setPassword/removePassword to throw NOT_FOUND instead of silently returning. When that lands, the "not-found path" assertions from Step 3 must be updated in the same PR — that test diff is the intended signal that behavior changed on purpose.
• Plan 005 changes the caller of statistics.increment (dedup), not its body, so Step 5's test should keep passing; if it breaks, 005 changed more than intended.
• A reviewer should check the mocks assert real branching, not tautologies (e.g. that NOT_FOUND comes from an empty RETURNING, not from a mock that always throws).