open-agreements
Version:
Open-source legal template filling CLI and library
155 lines (116 loc) • 4.16 kB
Markdown
Convert tests into Allure-readable behavioral specs that are easy to scan in reports and easy to debug on failure.
Use repo wrappers where available.
```ts
import { describe, expect } from 'vitest';
import { itAllure as it, allureStep, allureJsonAttachment } from '../testing/allure-test.js';
describe('Feature Name', () => {
it('Human-readable test title', async () => {
let result: { success: boolean };
await allureStep('Given some precondition', async () => {
await allureJsonAttachment('input', { key: 'value' });
});
await allureStep('When I perform an action', async () => {
result = { success: true };
});
await allureStep('Then the result is correct', async () => {
expect(result!.success).toBe(true);
});
});
});
```
If direct Allure calls are required:
- import from `allure-js-commons`
- `await` every Allure API call
- never import test APIs from `allure-vitest`
```ts
await allureStep('Then everything works', async () => {
expect(result.status).toBe('success');
expect(result.count).toBe(5);
expect(result.items[0].name).toBe('foo');
});
```
```ts
await allureStep('Then status is success', async () => {
expect(result.status).toBe('success');
});
await allureStep('And count is 5', async () => {
expect(result.count).toBe(5);
});
await allureStep("And first item is 'foo'", async () => {
expect(result.items[0].name).toBe('foo');
});
```
Use explicit step prefixes for report readability:
- Given
- And (additional setup)
- When
- Then
- And (additional expectations)
```ts
await allureStep('Given a logged-in user', async () => {
user = createUser();
});
await allureStep('When updating the profile name', async () => {
result = await updateProfile(user, { name: 'New Name' });
});
await allureStep('Then the update succeeds', async () => {
expect(result.success).toBe(true);
});
```
Add context that makes failures diagnosable without rerunning locally.
```ts
await allureJsonAttachment('request', requestPayload);
await allureJsonAttachment('response', responsePayload);
```
Recommended attachment content:
- input fixtures
- mutation params
- normalized output
- conflict diagnostics
- error payloads
Default severity is `normal` in wrappers.
Use elevated severity selectively:
- `critical`: mutation correctness, data loss risk, security/path-policy guardrails
- `minor`: narrow edge-case behavior
- `*.test.ts`: standard collocated tests (default)
- Use Allure labels/steps/attachments inside these tests.
- Reserve `*.allure.test.ts` only for legacy files or explicit migration constraints.
Keep test files focused:
- one module or one capability per file
- avoid unrelated assertions in the same file
## Allure Report Hierarchy Notes
This repo uses package-level compat reporters and setup hooks to keep Allure 3 hierarchy stable.
Follow existing package conventions:
- `packages/safe-docx/src/testing/*`
- `packages/docx-primitives/test/helpers/*`
- `packages/docx-comparison/src/testing/*`
Do not replace compat reporter wiring in `vitest.config.ts` unless explicitly requested.
## Coverage-First Prioritization
When increasing coverage:
1. Rank by uncovered branches in high-blast-radius code.
2. Prioritize mutators, parser/serializer boundaries, and safety checks.
3. Add tests for strict/permissive modes and transactionality.
4. Verify targeted tests first, then package coverage.
## Commands
```bash
npm run test:run -w @usejunior/safe-docx
npm run test:run -w @usejunior/docx-primitives
npm run test:run -w @usejunior/docx-comparison
npm run test:coverage:packages
node scripts/report_package_coverage.mjs
```
## Quick Checklist Before Committing
- Test title is behavior-readable.
- Steps are Given/When/Then/And.
- One assertion per step where practical.
- Attachments added for nontrivial data paths.
- Error code/hint text validated for failure-path tests.