carrot-foundation/rule-testing

Rule testing

Apply this rule whenever work touches:

• *.spec.ts
• *.e2e.spec.ts
• *.test-cases.ts

All test code in this repository runs under Vitest. Tests must be deterministic, isolated, and free of real-world data.

Test file conventions

| Pattern | Purpose | |---|---| | {name}.spec.ts | Unit tests, co-located with source | | {name}.e2e.spec.ts | End-to-end / integration tests | | {name}.test-cases.ts | Shared test data and fixtures |

The test environment loads variables from .env-files/.env.test.

Data generation

Never hardcode test values that could be randomized. Use the following tools:

• @faker-js/faker for primitive values (strings, numbers, dates, UUIDs).
• zocker for generating objects that conform to a Zod schema.
• Shared stubs from @carrot-fndn/shared/testing:
  • stubRuleInput() - creates a valid RuleInput with sensible defaults.
  • stubDocument() - creates a valid document fixture.
  • createStubFromSchema() - generates a stub from any Zod schema.

No real data policy

Tests must never contain real-world identifiable information. Use obviously synthetic values:

| Field | Fake example | |---|---| | Company name | VERDE CAMPO LTDA, EXEMPLO INDUSTRIAS | | CNPJ | 11.222.333/0004-55, 77.888.999/0001-22 | | Vehicle plate | FKE1A23, HIJ3K56 | | Address | Rua Modelo, 100, Av. Principal, 500 | | Person name | Pedro Santos, Ana Ferreira |

This applies to raw OCR text fixtures as well: both the input text and expected assertion values must use fake data consistently.

Table-driven tests

When a function must be tested against multiple scenarios, use it.each:

it.each([
  { input: 0, expected: 'zero' },
  { input: 1, expected: 'one' },
  { input: 2, expected: 'two' },
])('converts $input to "$expected"', ({ input, expected }) => {
  expect(numberToWord(input)).toBe(expected);
});

Partial assertions

Prefer expect.objectContaining when only a subset of fields matters for the assertion. This keeps tests resilient to unrelated field additions:

expect(result).toEqual(
  expect.objectContaining({
    status: 'APPROVED',
    score: expect.any(Number),
  }),
);