Unit Test Philosophy

Risk-based unit testing and Allure-readable behavioral spec style for open-agreements. Use when user says "add tests," "test quality," "coverage expansion,"...

Security Scan

This is an instruction-only guidance skill about test style and priorities; its declared requirements and instructions are consistent with that purpose and it does not request extra access or installs.

Purpose & Capability

Name/description match the content: the skill provides testing philosophy, Allure-style conventions, file/path guidance, and command examples. It declares no binaries, env vars, or installs and does not require unrelated credentials or tooling.

Instruction Scope

SKILL.md contains purely prescriptive guidance, test templates, file/path conventions, and an npm command checklist; it does not instruct reading unrelated system files, exfiltrating data, or contacting external endpoints. It does reference repo paths and helper modules (expected for test guidance).

Install Mechanism

No install spec and no code files — the skill is instruction-only, so nothing is written to disk or fetched at install time.

Credentials

The skill requests no environment variables, credentials, or config paths. References to npm scripts and repo helpers are appropriate for a testing guide; nothing appears to require elevated secrets.

Persistence & Privilege

always is false and the skill does not request persistent system presence or modification of other skills. It is safe from a persistence/privilege perspective.

Assessment

This skill is guidance-only and appears coherent with its stated purpose. You can safely review and use its conventions and templates. Notes: if you allow the agent to run autonomously, an agent using this skill could suggest or attempt the npm commands listed — the skill itself does not fetch code or require credentials. Before running any test/coverage commands, confirm the referenced repo helper modules and scripts (e.g., integration-tests/helpers/allure-test.js, scripts/patch_allure_html_sanitizer.mjs) exist and that test attachments won't include sensitive data. If you prefer manual control, review the guidance and run the commands yourself rather than allowing autonomous invocation.

Unit Test Philosophy (Open Agreements)

Security model

• This skill is guidance only — it does not execute tests or modify code directly.
• All test commands are provided for the user or agent to run in their local environment.
• No network access, credentials, or external services are required.

Use this skill when

• A request asks to add tests, improve coverage, or harden regressions.
• A change touches src/, integration-tests/, packages/contracts-workspace, or packages/contracts-workspace-mcp.
• You need readable Allure behavior specs and OpenSpec traceability.

Core philosophy

1. Test highest-risk behavior first. Focus first on mutating flows, parser/validator boundaries, and policy/safety checks.
2. Optimize for regression prevention, not just line coverage. Prioritize branches where failures could produce wrong legal output or unsafe automation behavior.
3. Treat Allure as test style, not test type. Use normal unit/integration tests with Allure labels, steps, and attachments in the same files.
4. Keep spec and test effectively coextensive. If behavior is important enough to test, map it to canonical OpenSpec scenarios or active change-package scenarios.
5. Keep assertions behavior-oriented. Verify user-observable outputs, diagnostics, and mutation outcomes before internals.
6. Make failures easy to debug. Attach structured context for inputs, normalized outputs, and error payloads.

Repo standards

Test structure

• Use Given/When/Then/And wording in Allure step titles.
• Keep scenario steps as top-level test steps; avoid wrapping the full test body in synthetic container steps like Execute test body.
• Prefer one assertion per step where practical.
• Multiple assertions in one step are acceptable when they validate one cohesive invariant.
• Keep tests deterministic (fixed fixtures, explicit env flags, no timing assumptions).

Allure API

• Prefer repo helpers over direct raw Allure calls:
  • integration-tests/helpers/allure-test.ts
  • Common helpers: itAllure, testAllure, allureStep, allureJsonAttachment, allurePrettyJsonAttachment, allureWordLikeTextAttachment, allureParameter, allureSeverity
• Do not import from allure-vitest in tests.
• Keep helper usage consistent across src/**/*.test.ts and integration-tests/**/*.test.ts.
• For complex fixtures/stateful flows, attach:
  • a pretty JSON artifact for request/result payloads
  • a human-readable “Word-like” artifact for document/checklist state before and after mutation when relevant
• Rendering note: HTML preview attachments rely on the report post-process sanitizer allowlist patch (scripts/patch_allure_html_sanitizer.mjs, invoked by npm run report:allure). Do not bypass this pipeline when generating reports for review.

File naming and placement

• Use collocated test files like src/<module>.test.ts.
• Add Allure style inside these tests; do not split by "allure-only" test types by default.
• Keep one test file focused on one module or capability.
• Migration policy: gradually rename legacy *.allure.test.ts files to *.test.ts; do not introduce new *.allure.test.ts files.

OpenSpec traceability

• Use .openspec('OA-###') whenever a matching scenario ID exists for the behavior.
• Scenario IDs may come from either canonical specs (openspec/specs/open-agreements/spec.md) or active change-package specs (openspec/changes/<change-id>/specs/open-agreements/spec.md).
• Pre-canonical IDs from active change packages are valid during implementation and should remain stable when promoted into canonical specs.
• For new important behavior, add scenario IDs in the active change package first, map tests immediately, then promote those IDs into canonical specs when archiving.

Coverage expansion workflow

1. Read coverage summaries and identify branch-heavy modules in src/core/** and integration flows.
2. Rank by blast radius and mutation risk.
3. Add tests in this order:
   • Validation and error branches
   • Strict vs permissive behavior
   • No-partial-mutation / transactional guarantees
   • Invariants (deterministic outputs, schema safety, idempotency)
4. Run targeted tests first, then full suite and coverage.

Severity recommendation rubric

• critical: mutation correctness, legal-output integrity, data-loss risk, security/policy guardrails.
• normal: standard behavior and compatibility scenarios.
• minor: narrow edge cases with low production impact.
• Apply severity based on failure impact, not module ownership.

Command checklist

npm run test:run
npm run test:coverage
npm run check:spec-coverage
npm run check:allure-labels

Minimal test template (TypeScript)

import { describe, expect } from 'vitest';
import { itAllure as it, allureStep, allureJsonAttachment } from '../../../integration-tests/helpers/allure-test.js';

describe('checklist patch behavior', () => {
  it('applies replacement deterministically', async () => {
    let result: { ok: boolean };

    await allureStep('Given a valid patch payload', async () => {
      await allureJsonAttachment('patch-input.json', {
        patch_id: 'patch_001',
        operations: [{ op: 'replace', path: '/issues/0/status', value: 'CLOSED' }],
      });
    });

    await allureStep('When patch validation runs', async () => {
      result = { ok: true };
    });

    await allureStep('Then validation succeeds', async () => {
      expect(result!.ok).toBe(true);
    });
  });
});

Extended reference

• See references/allure-test-spec-writing-guide.md for full Allure step-writing guidance.