Understanding the Tiered Test Loop for ai-memory Development

The ai-memory project employs a two-tiered test loop that separates rapid everyday validation (cargo t) from exhaustive pre-merge checks (cargo tf), enabling fast feedback while ensuring production-grade reliability.

The akitaonrails/ai-memory repository is a Rust-based memory management system for AI applications that optimizes developer velocity through a sophisticated tiered test loop strategy. This approach categorizes tests by execution characteristics, allowing developers to iterate quickly during local development while enforcing comprehensive validation through automated gates before any code reaches the main branch.

The Two-Tier Architecture

The testing strategy divides the suite into distinct tiers based on execution speed and resource requirements. This separation is enforced through module naming conventions and nextest profile configurations documented in the repository's build instructions.

Everyday Fast Loop

The everyday loop targets sub-20-second feedback cycles for active development. This tier executes only unit tests that lack slow or stress path prefixes, using the nextest runner for parallel execution and fast compilation.

# Run the everyday fast loop (default nextest profile)

cargo t

# Equivalent explicit command

cargo nextest run

According to the repository documentation in README.md (lines 93-123), this loop represents the standard development workflow, providing immediate feedback on logic correctness without the overhead of integration or performance tests.

Full Tier (Slow and Stress Tests)

The full tier encompasses the entire test suite, including integration tests, end-to-end workflows, and stress benchmarks. Tests belong to this tier when their module path contains a segment beginning with slow or stress, such as tests::slow_integration or stress::concurrent_memory_pressure.

# Execute the full tier including all slow/stress tests

cargo tf

# Run only slow-tier tests explicitly

cargo nextest run -E 'test(slow)'

This tier serves as the quality gate enforced by CI pipelines before merging pull requests.

Test Classification Rules

The tier assignment relies on strict naming conventions within the source tree. Any test residing in a module whose path starts with slow or stress is automatically excluded from the everyday loop.

Key implementation details include:

• Module Path Matching: Tests in crate::slow_database::connection_pool or crate::stress::memory_leak_detection run exclusively under cargo tf
• File System Patterns: Physical test files named slow_*.rs or located in tests/slow/ directories map to the slow tier
• Example Location: crates/ai-memory-store/tests/slow_integration.rs contains database integration tests that require external services

Running the Test Loops Locally

Developers interact with the system through Cargo aliases defined in the workspace configuration. The following examples demonstrate the standard workflow:

# 1. Local development - fast feedback loop

cargo t

# 2. Pre-commit validation - includes slow tests

cargo tf

# 3. Continuous integration simulation

cargo nextest run --profile ci

# 4. Debugging a specific slow test

cargo nextest run --test-threads 1 slow_persistence_recovery

The cargo tf command expands to a nextest invocation using the full profile, which overrides the default test exclusions and executes every discovered test in the workspace.

CI/CD Integration and Quality Gates

The repository enforces the full tier through GitHub Actions workflows defined in .github/workflows/ci.yml. These pipelines execute cargo tf on every pull request, ensuring that slow and stress tests pass before code merges.

The workflow typically follows this pattern:

1. Fast check: Run cargo check and cargo clippy for immediate linting
2. Everyday tier: Execute cargo t to catch logic errors quickly
3. Full tier gate: Run cargo tf to validate integration and performance
4. Binary release: Only proceed if the full tier succeeds

Key Files and Configuration

File	Purpose	Relevant Content
README.md	Documents the tiered test strategy	Lines 93-123 describe the everyday loop and full tier commands
Cargo.toml	Workspace configuration	Defines cargo t and cargo tf aliases via [alias] sections
.github/workflows/ci.yml	CI enforcement	Executes full tier on pull requests and pushes to main
crates/*/tests/slow_*.rs	Slow tier test modules	Integration and stress tests excluded from fast loop

Summary

• Two-tier system: The everyday loop (cargo t) provides rapid feedback during development, while the full tier (cargo tf) guarantees comprehensive coverage before merging.
• Naming convention: Tests in modules prefixed with slow or stress automatically belong to the full tier only.
• Local efficiency: Developers can iterate in ~20 seconds using the fast loop without waiting for resource-intensive tests.
• CI enforcement: GitHub Actions runs the full tier on every pull request, preventing regressions in integration or performance boundaries.

Frequently Asked Questions

What is the difference between cargo t and cargo tf in ai-memory?

cargo t runs the everyday fast loop, executing only quick unit tests that complete in seconds and have no slow or stress prefix in their module path. cargo tf runs the full tier, which includes all tests regardless of naming conventions, specifically targeting integration tests and stress benchmarks that may take minutes to complete.

How do I mark a test as belonging to the slow or stress tier?

Place the test inside a module whose path contains a segment starting with slow or stress. For example, organize the test under mod slow_integration or place the file in a tests/slow/ directory. The nextest configuration automatically detects these path patterns and excludes them from the default everyday profile while including them in the full tier profile.

Why does the everyday loop exclude slow tests excluding external dependencies?

The everyday loop prioritizes developer velocity by eliminating tests that require database connections, network I/O, or long-running computations. This ensures feedback within ~20 seconds, maintaining flow state during iterative coding sessions while reserving expensive validation for pre-merge checks.

Which CI checks run the full tier before merging?

The .github/workflows/ci.yml workflow executes cargo tf (the full tier) on every pull request and push to protected branches. This gate prevents code that passes fast unit tests but fails integration or stress scenarios from entering the main branch, ensuring binary releases only ship after exhaustive validation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}