rust-testing
Codex-RS Contributors Rust Testing Best Practices
A comprehensive guide to writing high-quality Rust tests at the standard established by the top codex-rs contributors. This skill encodes patterns for test architecture, assertions, mock servers, test data, event-driven testing, determinism, snapshot testing, and integration test infrastructure.
When to Apply
- Writing new tests for any Rust module in codex-rs
- Adding regression tests for a bug fix (3-6 tests per PR)
- Creating integration tests that interact with the Responses API via SSE mocks
- Modifying TUI rendering code that requires snapshot coverage
- Reviewing test code for adherence to codebase conventions
Rule Categories by Priority
| Priority | Category | Prefix | Rules | Focus |
|---|---|---|---|---|
| CRITICAL | Test Architecture | arch- |
6 | File organization, imports, isolation |
| CRITICAL | Assertions | assert- |
5 | pretty_assertions, whole-object comparison |
| HIGH | Mock Servers | mock- |
6 | wiremock, SSE builders, ResponseMock |
| HIGH | Test Data | data- |
5 | Builders, typed construction, BTreeMap |
| MEDIUM-HIGH | Event Testing | event- |
5 | submit/wait cycles, predicate matching |
| MEDIUM | Determinism | det- |
5 | Stable IDs, environment isolation |
| MEDIUM | Snapshot Testing | snap- |
4 | Insta workflow, buffer rendering |
| LOW-MEDIUM | Integration Tests | integ- |
4 | core_test_support, Bazel compatibility |
Quick Reference
- Test file placement: Sibling
_tests.rsvia#[path = "feature_tests.rs"] - Assertions: Always
use pretty_assertions::assert_eq; - Object comparison:
assert_eq!(actual, expected)on entire structs - SSE mocking:
responses::mount_sse_once+responses::sse(vec![ev_*(...)]) - Event waiting:
wait_for_event(codex, |ev| predicate) - Snapshot tests:
insta::assert_snapshot!(terminal.backend()) - Determinism:
BTreeMapoverHashMap,set_deterministic_process_ids - Binary resolution:
codex_utils_cargo_bin::cargo_bin("name") - Fixture paths:
codex_utils_cargo_bin::find_resource!("path") - Sandbox handling:
skip_if_sandbox!()/skip_if_no_network!()
How to Use
- Start with CRITICAL rules (arch, assert) — these apply to every test
- Apply HIGH rules (mock, data) when writing integration tests with API mocks
- Apply MEDIUM-HIGH rules (event) when testing the agent protocol
- Apply MEDIUM rules (det, snap) when tests involve process IDs or UI rendering
- Apply LOW-MEDIUM rules (integ) for cross-crate and build-system compatibility
Reference Files
| File | Purpose |
|---|---|
references/_sections.md |
Section definitions, ordering, and impact levels |
references/arch-*.md |
Test architecture rules (6 files) |
references/assert-*.md |
Assertion rules (5 files) |
references/mock-*.md |
Mock server rules (6 files) |
references/data-*.md |
Test data rules (5 files) |
references/event-*.md |
Event testing rules (5 files) |
references/det-*.md |
Determinism rules (5 files) |
references/snap-*.md |
Snapshot testing rules (4 files) |
references/integ-*.md |
Integration test rules (4 files) |
assets/templates/_template.md |
Rule file template |
metadata.json |
Skill metadata and version |
More from pproenca/dot-skills
zod
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
2.0Kclean-architecture
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
1.4Kemilkowal-animations
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
918vitest
Vitest testing framework patterns for test setup, async testing, mocking with vi.*, snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
907typescript
This skill should be used when the user asks to "optimize TypeScript performance", "speed up tsc compilation", "configure tsconfig.json", "fix type errors", "improve async patterns", or encounters TS errors (TS2322, TS2339, "is not assignable to"). Also triggers on .ts, .tsx, .d.ts file work involving type definitions, module organization, or memory management. Does NOT cover TypeScript basics, framework-specific patterns, or testing.
821nuqs
nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
735