| name | testing |
| description | Vitest testing guide for uniku. Use when writing or updating library, CLI, integration, Cloudflare e2e, benchmark-result, or Effect-based CLI tests; fixing failing tests; improving coverage; setting up mocks; reviewing test quality; or writing Effect v4 @effect/vitest tests. |
Testing
Core Posture
Follow root AGENTS.md for repo-wide verification, runtime-portability, package-entrypoint, and Effect migration rules. This skill adds test-shape and test-tool guidance.
Inspect the package's existing scripts and vitest.config.ts before inventing a command or layout. Prefer the narrowest command that exercises the changed behavior, then broaden before handoff when the change touches shared code.
pnpm --filter uniku test:unit -- path/to/file.test.ts
pnpm --filter uniku test:integration
pnpm --filter @uniku/cli test -- path/to/file.test.ts
pnpm test:e2e:cloudflare
Use the package's actual scripts. Do not run the full suite first when a focused test can reproduce the issue.
Test Shape
Use the repo's current layout before adding a new one.
| Kind | Typical location | Notes |
|---|
| Library unit | packages/uniku/__tests__/unit/**/*.test.ts | Pure generator, codec, random pool, and timestamp logic |
| Library integration | packages/uniku/__tests__/integration/**/*.test.ts | Cross-validation against reference packages |
| Runtime e2e | packages/uniku/__tests__/e2e/runtimes/cloudflare/** | Cloudflare Workers compatibility |
| CLI tests | packages/cli/__tests__/**/*.test.ts | Command behavior, service boundaries, output, stdin, update checks |
| Package config | packages/*/vitest.config.ts | Package scripts should delegate to Vitest projects |
New production files should usually ship with sibling or package-local tests in the same change. If behavior crosses a public boundary, test through the public API instead of private helper calls.
Principles
- Test externally observable behavior: generated IDs, byte/codecs, validation results, CLI output, typed failures, process exit behavior, or public API contracts.
- Prefer integration-level assertions over white-box param-forwarding tests. Keep low-level tests only when they isolate tricky behavior not covered above.
- Mock at boundaries: clocks, random bytes, network, stdin/stdout/stderr, process env, browser globals, and external packages.
- Avoid mocking internal modules just to assert call plumbing.
- Keep unit tests deterministic. No live network, real timers, random data without a seeded generator, or process-wide state that leaks between tests.
- Expected failures are data. CLI tests run on
@effect/vitest v4 (it.effect, layer(...), effect/testing/TestConsole): read effect-vitest.md and verify v4 APIs against repos/effect.
- Assert type-safely; never branch in a test body. An
if wrapped around assertions silently skips them when its guard is false. For current Vitest tests, use assertions that narrow or fail immediately; for Effect v4 tests, use the narrowing helpers described in effect-vitest.md.
- After one or two failed fix attempts, reassess whether the test reveals a product bug, a stale assertion, or low-value coupling.
Reference Map
Open only the reference needed for the current task:
| File | Open when |
|---|
| vitest-basics.md | Writing plain Vitest tests, setup/teardown, spies, globals, or module isolation |
| effect-vitest.md | Writing @effect/vitest tests, asserting typed Effect failures, or checking v4 test APIs |
| layers-services.md | Providing Effect services with layers or building reusable test service fixtures |
| property-tests.md | Adding Schema-backed property tests or custom generators |
| time-and-troubleshooting.md | Handling TestClock, live runtimes, failing tests, pollution, hanging tests, or test review |
Handoff
Run the relevant broader package or repo checks before finishing behavioral, public API, or adapter changes. Use the full handoff command set from root AGENTS.md when the change warrants it.
