🦄 new(testing): add property-based testing with fast-check

[UniquePixels]

Summary

Integrate fast-check for property-based testing alongside the existing example-based Bun test suite.

Motivation

Property-based testing generates random inputs to find edge cases that hand-written examples miss. Good candidates in Unicorn:

• attempt() — verify error wrapping holds for arbitrary thrown values (strings, errors, objects, undefined)
• Schema helpers — validate that snowflakeId, secretString, and config schemas reject/accept arbitrary inputs correctly
• Component pattern matching — verify parameterized ID parsing with arbitrary string patterns
• Guard composition — verify guard chains short-circuit correctly with arbitrary pass/fail combinations

Scope

• Install fast-check as a dev dependency
• Add property-based tests alongside existing tests (not replacing them)
• Start with attempt() and schema helpers as initial targets
• Document pattern in .claude/testing-reference.md

References

• fast-check docs
• Bun + fast-check compatibility

[coderabbitai]

Coding Plan

Summary

• Install fast-check as a dev dependency without any test runner configuration changes (Bun supports it natively)
• Extend existing test files with new describe blocks for property tests rather than creating separate files
• Focus property tests on invariants and boundary conditions that are tedious to enumerate manually: Snowflake digit-length boundaries, Result monad laws, envMap tuple selection
• Document the pattern in testing-reference.md so future property tests follow a consistent style

Implementation Steps

Phase 1: Dependency Setup

Install fast-check and verify it integrates with the existing Bun test runner without configuration changes.

Install fast-check

Add fast-check as a development dependency using the Bun package manager.

• Run bun install -D fast-check to add the dependency to package.json
• Verify the package installs correctly and is listed in devDependencies

🤖 Prompt for AI agents

Install fast-check as a dev dependency using the Bun package manager. No
configuration changes are needed as Bun supports fast-check natively.

- Run `bun install -D fast-check` to add the dependency
- Verify the package appears in `devDependencies` in `package.json`

Phase 2: Property-Based Tests for Core Modules

Add property-based tests to the existing test files for attempt() and schema helpers. These tests will be organized in new describe blocks within the existing test files, following the established pattern of nested describes by feature.

Task 1: Property Tests for attempt() Module

Add a new describe('property-based tests') block to the existing attempt test file covering the Result monad invariants and error-wrapping guarantees.

• Update src/core/lib/attempt/index.test.ts to add property tests
• Import fast-check: import fc from 'fast-check';
• Test that attempt() never throws for any arbitrary function (sync or async) — it always returns a Result
• Test that successful functions produce Ok containing the exact returned value for arbitrary values (primitives, objects, arrays, undefined, null)
• Test that Error throws are preserved as-is in the Err result
• Test that non-Error throws (strings, numbers, objects, symbols) are wrapped in Error with the original as cause
• Test Ok's map applies transformation correctly for arbitrary functions and values
• Test Err's map is a no-op returning the same error for any transformation
• Test unwrapOr on Ok returns the value (ignoring default) for arbitrary value/default pairs
• Test unwrapOr on Err returns the default for arbitrary error/default pairs
• Test match always calls the correct handler branch for any Result

Task 2: Property Tests for Snowflake Schema

Add property tests to the existing schema-helpers test file validating the Snowflake boundary conditions.

• Update src/core/configuration/schema-helpers.test.ts to add a describe('Snowflake property tests') block
• Test that any string of exactly 17, 18, or 19 digits always parses successfully
• Test that any string shorter than 17 digits always fails
• Test that any string longer than 19 digits always fails
• Test that any string containing non-digit characters always fails
• Test that non-string values (numbers, objects, null, undefined) always fail
• Use fc.stringOf(fc.constantFrom(...'0123456789')) to generate digit-only strings of controlled lengths

Task 3: Property Tests for envMap Schema

Add property tests validating envMap's tuple selection logic.

• Add a describe('envMap property tests') block to schema-helpers.test.ts
• Test that bare values pass through unchanged for any valid schema value
• Test that single-element tuples [v] always return v
• Test that two-element tuples [prod, dev] return index 0 when isProduction=true
• Test that two-element tuples [prod, dev] return index 1 when isProduction=false
• Use Snowflake-compatible generators since envMap is typically used with Snowflake schema

Task 4: Property Tests for Secret and MiscValue Schemas

Add property tests for secret reference resolution edge cases.

• Add describe('Secret property tests') block to schema-helpers.test.ts
• Test that valid secret:// references with valid key names and set env vars always resolve
• Test that invalid key patterns (containing invalid characters) always fail
• Test that references to unset env vars always fail
• Add describe('MiscValue property tests') block
• Test that non-string values pass through unchanged for arbitrary values (numbers, booleans, objects, arrays)
• Test that strings not starting with secret:// pass through unchanged
• Use beforeEach/afterEach with the existing makeEnvRestorer() pattern to manage env state

🤖 Prompt for AI agents

Add property-based tests to the existing test files for `attempt()` and schema
helpers. All property tests should be placed in new `describe` blocks within the
existing test files — do not create new files. Import fast-check with `import fc
from 'fast-check';` at the top of each file.

**`src/core/lib/attempt/index.test.ts`** — Add `describe('property-based
tests')` block:
- Test `attempt()` never throws for any arbitrary sync or async function — it
always returns a Result
- Test successful functions produce Ok containing the exact returned value for
arbitrary values (primitives, objects, arrays, undefined, null)
- Test that Error throws are preserved as-is in the Err result
- Test that non-Error throws (strings, numbers, objects, symbols) are wrapped in
Error with the original as `cause`
- Test Ok's `map` applies transformation correctly for arbitrary functions and
values
- Test Err's `map` is a no-op returning the same error for any transformation
- Test `unwrapOr` on Ok returns the value (ignoring default) for arbitrary
value/default pairs
- Test `unwrapOr` on Err returns the default for arbitrary error/default pairs
- Test `match` always calls the correct handler branch for any Result

**`src/core/configuration/schema-helpers.test.ts`** — Add the following
`describe` blocks:

`describe('Snowflake property tests')`:
- Test strings of exactly 17, 18, or 19 digits always parse successfully
- Test strings shorter than 17 digits always fail
- Test strings longer than 19 digits always fail
- Test strings containing non-digit characters always fail
- Test non-string values (numbers, objects, null, undefined) always fail
- Use `fc.stringOf(fc.constantFrom(...'0123456789'))` to generate digit-only
strings of controlled lengths

`describe('envMap property tests')`:
- Test bare values pass through unchanged for any valid schema value
- Test single-element tuples `[v]` always return `v`
- Test two-element tuples `[prod, dev]` return index 0 when isProduction=true
- Test two-element tuples `[prod, dev]` return index 1 when isProduction=false
- Use Snowflake-compatible generators

`describe('Secret property tests')`:
- Test valid `secret://` references with valid key names and set env vars always
resolve
- Test invalid key patterns (containing invalid characters) always fail
- Test references to unset env vars always fail
- Use `beforeEach`/`afterEach` with the existing `makeEnvRestorer()` pattern to
manage env state

`describe('MiscValue property tests')`:
- Test non-string values pass through unchanged for arbitrary values (numbers,
booleans, objects, arrays)
- Test strings not starting with `secret://` pass through unchanged

Phase 3: Documentation

Update the testing reference to document fast-check patterns for future contributors.

Update Testing Reference Documentation

Add a new section to the testing reference documenting property-based testing patterns.

• Update .claude/testing-reference.md to add a "Property-Based Testing" section
• Document the import pattern: import fc from 'fast-check';
• Document the basic structure: fc.assert(fc.property(fc.arbitrary(), (value) => { /* assertion */ }))
• Provide examples of common arbitraries used in the codebase (digit strings for Snowflakes, arbitrary values for attempt)
• Note that property tests complement example-based tests and should be placed in their own describe block
• Reference the Bun + fast-check compatibility documentation

🤖 Prompt for AI agents

Update `.claude/testing-reference.md` to add a "Property-Based Testing" section
documenting fast-check patterns for future contributors.

The new section should include:
- The import pattern: `import fc from 'fast-check';`
- The basic usage structure: `fc.assert(fc.property(fc.arbitrary(), (value) => {
/* assertion */ }))`
- Examples of common arbitraries used in the codebase (e.g., digit strings for
Snowflakes, arbitrary values for `attempt()`)
- A note that property tests complement example-based tests and should be placed
in their own `describe` block within existing test files
- A reference to Bun + fast-check compatibility documentation

Research

Unicorn is a Discord bot framework using Bun as its runtime and test runner. Tests follow a co-located pattern where *.test.ts files sit alongside their source modules. The codebase enforces 100% test coverage via bunfig.toml and uses helpers from @/core/lib/test-helpers. The two target modules for property testing are: src/core/lib/attempt/index.ts (Result monad with Ok/Err classes and the attempt() wrapper) and src/core/configuration/schema-helpers.ts (Zod schemas for Snowflake IDs, secret references, envMap, and MiscValue). Both already have comprehensive example-based tests that property tests will complement, not replace.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Install fast-check as a dev dependency using the Bun package manager. No
configuration changes are needed as Bun supports fast-check natively.

- Run `bun install -D fast-check` to add the dependency
- Verify the package appears in `devDependencies` in `package.json`
===============================================================================

Task: 2

Add property-based tests to the existing test files for `attempt()` and schema
helpers. All property tests should be placed in new `describe` blocks within the
existing test files — do not create new files. Import fast-check with `import fc
from 'fast-check';` at the top of each file.

**`src/core/lib/attempt/index.test.ts`** — Add `describe('property-based
tests')` block:
- Test `attempt()` never throws for any arbitrary sync or async function — it
always returns a Result
- Test successful functions produce Ok containing the exact returned value for
arbitrary values (primitives, objects, arrays, undefined, null)
- Test that Error throws are preserved as-is in the Err result
- Test that non-Error throws (strings, numbers, objects, symbols) are wrapped in
Error with the original as `cause`
- Test Ok's `map` applies transformation correctly for arbitrary functions and
values
- Test Err's `map` is a no-op returning the same error for any transformation
- Test `unwrapOr` on Ok returns the value (ignoring default) for arbitrary
value/default pairs
- Test `unwrapOr` on Err returns the default for arbitrary error/default pairs
- Test `match` always calls the correct handler branch for any Result

**`src/core/configuration/schema-helpers.test.ts`** — Add the following
`describe` blocks:

`describe('Snowflake property tests')`:
- Test strings of exactly 17, 18, or 19 digits always parse successfully
- Test strings shorter than 17 digits always fail
- Test strings longer than 19 digits always fail
- Test strings containing non-digit characters always fail
- Test non-string values (numbers, objects, null, undefined) always fail
- Use `fc.stringOf(fc.constantFrom(...'0123456789'))` to generate digit-only
strings of controlled lengths

`describe('envMap property tests')`:
- Test bare values pass through unchanged for any valid schema value
- Test single-element tuples `[v]` always return `v`
- Test two-element tuples `[prod, dev]` return index 0 when isProduction=true
- Test two-element tuples `[prod, dev]` return index 1 when isProduction=false
- Use Snowflake-compatible generators

`describe('Secret property tests')`:
- Test valid `secret://` references with valid key names and set env vars always
resolve
- Test invalid key patterns (containing invalid characters) always fail
- Test references to unset env vars always fail
- Use `beforeEach`/`afterEach` with the existing `makeEnvRestorer()` pattern to
manage env state

`describe('MiscValue property tests')`:
- Test non-string values pass through unchanged for arbitrary values (numbers,
booleans, objects, arrays)
- Test strings not starting with `secret://` pass through unchanged
===============================================================================

Task: 3

Update `.claude/testing-reference.md` to add a "Property-Based Testing" section
documenting fast-check patterns for future contributors.

The new section should include:
- The import pattern: `import fc from 'fast-check';`
- The basic usage structure: `fc.assert(fc.property(fc.arbitrary(), (value) => {
/* assertion */ }))`
- Examples of common arbitraries used in the codebase (e.g., digit strings for
Snowflakes, arbitrary values for `attempt()`)
- A note that property tests complement example-based tests and should be placed
in their own `describe` block within existing test files
- A reference to Bun + fast-check compatibility documentation

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!