PSA/ee/docs/planning/adhoc/2026-01-27-biz-test-coverage-analysis/PRD.md

Business-Relevant Test Counterpart Loop

Goal

Create a 1:1 business-relevant counterpart for every notification-only fixture. Each current fixture that only calls notifications.send_in_app needs a corresponding fixture that exercises real domain-modifying actions.

Current State

• 171 total fixtures in workflow-harness
• 24 business-relevant (14%) - already call domain-modifying actions
• 144 notification-only - need business counterparts
• 2 scaffold (1%) - minimal harness tests (ticket-created-hello, ticket-created-ignore-system)
• 3 harness tests (2%) - runtime/schema validation tests

Classification Criteria

Classification	Definition	Needs Counterpart?
business-relevant	Calls domain-modifying actions: tickets.assign, tickets.add_comment, tickets.update_fields, projects.create_task, time_entries.create, email.send, crm.create_activity_note, scheduling.assign_user, etc.	No
notification-only	Only calls notifications.send_in_app	Yes
scaffold	No action.call at all (just state.set/assign/return)	No (intentional)
harness-test	Tests runtime behavior (paused workflows, schema validation)	No (infrastructure)

The Iteration Loop

Process fixtures domain by domain, alphabetically within each domain.

Phase 1: High-Value Domains First

1. ticket (71 needed) - highest impact, most complex business logic
2. project (28 needed) - task management, status workflows
3. invoice (10 needed) - billing automation
4. appointment (9 needed) - field service scheduling

Phase 2: Remaining Domains

5. payment (4 needed)
6. contract (4 needed)
7. schedule (4 needed)
8. technician (4 needed)
9. company (2 needed)
10. integration (2 needed)
11. task (2 needed)
12. time (2 needed)
13. email (1 needed)
14. capacity (1 needed)

Step-by-step: For Each Notification-Only Fixture

1. Read the current fixture

cat ee/test-data/workflow-harness/<current-fixture>/bundle.json
cat ee/test-data/workflow-harness/<current-fixture>/test.cjs

Understand:

• What event triggers it
• What the fixture name implies it should do
• What control flow patterns it uses (if/else, foreach, tryCatch, callWorkflow)

2. Design the business-relevant counterpart

The counterpart should:

• Use the same event as the original
• Preserve the same control flow pattern (if the original tests foreach, the counterpart should too)
• Replace notifications.send_in_app with domain-modifying action(s)
• Have a name that reflects the actual business action (see needed-biz-tests.json for suggestions)

3. Scaffold the new fixture

node tools/workflow-harness/scaffold.cjs \
  --name <suggested-biz-name> \
  --event <EVENT_NAME> \
  --schema <payload.Schema.v1>

4. Implement the bundle.json

Copy the control flow structure from the original, then:

• Replace notifications.send_in_app action calls with domain actions
• Update dependencies.actions array
• Update inputMapping for the new action's required fields
• Keep fixture markers (vars.marker, dedupe keys) for test isolation

Example transformation:

// BEFORE (notification-only)
{
  "id": "notify",
  "type": "action.call",
  "config": {
    "actionId": "notifications.send_in_app",
    "inputMapping": {
      "title": { "$expr": "vars.title" },
      "body": { "$expr": "vars.body" }
    }
  }
}

// AFTER (business-relevant)
{
  "id": "add-comment",
  "type": "action.call",
  "config": {
    "actionId": "tickets.add_comment",
    "version": 1,
    "inputMapping": {
      "ticket_id": { "$expr": "payload.ticketId" },
      "comment": { "$expr": "vars.marker & ' ' & vars.body" },
      "is_internal": true
    }
  }
}

5. Implement the test.cjs

The test must:

1. Create prerequisite domain objects (ticket, project, etc.)
2. Register cleanup hooks (HTTP delete with DB fallback)
3. Trigger the event via /api/workflow/events
4. Wait for the run to complete
5. Assert the business outcome by querying the DB

// Assert the domain action happened
const comments = await ctx.db.query(`
  SELECT * FROM comments
  WHERE ticket_id = $1 AND comment LIKE $2
`, [ticketId, `[fixture ${testId}]%`]);
ctx.expect.ok(comments.rows.length > 0, 'comment was created');

6. Run and iterate

node tools/workflow-harness/run.cjs \
  --test ee/test-data/workflow-harness/<new-fixture> \
  --base-url http://localhost:3010 \
  --tenant <uuid> \
  --cookie-file <path> \
  --pg-url <postgres-url> \
  --force --debug

Triage failures:

• Fixture bug: Wrong JSONata, missing fields, bad cleanup → fix in fixture
• Harness bug: Auth issues, polling errors → fix in tools/workflow-harness/
• Product bug: Action fails unexpectedly → fix in server/

7. Commit when green

git add ee/test-data/workflow-harness/<new-fixture>/
git commit -m "test(workflow-harness): add <new-fixture> business counterpart for <original-fixture>"

8. Update progress tracker

Mark the fixture as done in SCRATCHPAD.md and proceed to next.

Batching Strategy

Given 144 fixtures to create, batch by domain:

Domain	Count	Estimated Batches
ticket	71	7 batches of 10
project	28	3 batches of ~10
invoice	10	1 batch
appointment	9	1 batch
others	26	3 batches

Total: ~16 commit batches

Files

• Coverage analysis: coverage-analysis.json
• Needed tests with suggestions: needed-biz-tests.json
• Progress tracker: SCRATCHPAD.md

Definition of Done

• All 144 notification-only fixtures have business-relevant counterparts
• Each counterpart passes with --force --debug
• Each counterpart asserts a real database change (not just run SUCCEEDED)
• All fixtures committed with descriptive messages

When complete, output <promise>DONE</promise>.