Testing - Annie Mei

Annie Mei uses Rust’s built-in testing framework along with code quality tools to maintain high standards.

Running Tests

Rust’s testing framework is built into cargo:

Run All Tests

cargo test --all-features

This runs:

Unit tests (in #[cfg(test)] modules)
Integration tests (in tests/ directory)
Documentation tests (in doc comments)

Run Specific Tests

Test a specific module:

cargo test commands::ping

Run tests matching a pattern:

cargo test happy_path

Run a single test function:

cargo test ping_happy_path_returns_message_with_greeting

Show Test Output

By default, Rust captures stdout/stderr. To see print statements:

cargo test -- --nocapture

Show all output including passing tests:

cargo test -- --show-output

Writing Tests

Unit Tests

Unit tests live in the same file as the code being tested, in a #[cfg(test)] module:

src/commands/ping.rs

// ── Tests ───────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ping_happy_path_returns_message_with_greeting() {
        let response = handle_ping("<@123456>");

        assert!(response.is_message(), "expected Message variant");
        let text = response.unwrap_message();
        assert!(
            text.contains("<@123456>"),
            "response should mention the user"
        );
        assert!(
            text.contains("Annie Mei"),
            "response should mention the bot name"
        );
    }

    #[test]
    fn ping_response_includes_bot_description() {
        let text = handle_ping("<@999>").unwrap_message();
        assert!(text.contains("anime, manga"));
    }
}

See src/commands/ping.rs for the complete implementation.

Test Patterns

Annie Mei follows a testable architecture pattern:

Core logic - Transport-agnostic, pure functions
Adapter - Thin wrapper that calls Serenity APIs

Example from src/commands/ping.rs:

// ── Core logic (transport-agnostic) ─────────────────────────────────────

/// Produce the `/ping` response for the given user mention string.
///
/// This is the testable entry-point — it never touches `Context` or
/// `CommandInteraction`.
pub fn handle_ping(user_mention: &str) -> CommandResponse {
    CommandResponse::Message(format!(
        "Hi {user_mention}! I'm Annie Mei, awake and ready to help with anime, manga, recommendations, and theme songs.",
    ))
}

// ── Serenity adapter (thin wrapper) ─────────────────────────────────────

pub async fn run(ctx: &Context, interaction: &CommandInteraction) {
    configure_sentry_scope("Ping", interaction.user.id.get(), None);
    let _ = run_with_http(&ctx.http, interaction).await;
}

This separation allows testing handle_ping() without mocking Discord APIs.

Integration Tests

The tests/discord_plumbing.rs suite exercises Discord’s HTTP protocol without Discord credentials:

cargo test --test discord_plumbing

It deserializes synthetic interaction fixtures into Serenity models and directs Serenity’s real HTTP client to a local mock server. The suite verifies:

/ping sends the expected immediate callback request
invalid /anime input defers, then edits the original interaction response

Fixtures in tests/fixtures/interactions/ use synthetic IDs and tokens. The suite does not call Discord, AniList, MyAnimeList, Spotify, the LLM provider, PostgreSQL, or Redis. The shared BotCommand catalog in src/commands/mod.rs owns command names, definitions, and dispatch. Its unit tests verify unique names and matching definitions when you run the complete test suite. src/lib.rs exposes command modules to integration tests while src/main.rs remains the executable entry point.

Live Discord smoke tests

Use a private test application and Discord server only when you need to verify the real Gateway, global command registration, permissions, or Discord client rendering. Do not use production credentials or infrastructure. After starting the bot, verify /ping, a deferred /anime response, invalid /anime input, and one /settings component interaction. A member must invoke slash commands in the Discord client; bot accounts cannot invoke them on a member’s behalf.

Mocking External APIs

For commands that call external APIs (AniList, MAL, Spotify), mock the responses:

#[cfg(test)]
mod tests {
    use super::*;

    /// Helper: build a minimal `Anime` from JSON for testing.
    fn sample_anime() -> Anime {
        serde_json::from_value(serde_json::json!({
            "type": "ANIME",
            "id": 21,
            "idMal": 21,
            "title": {
                "romaji": "One Piece",
                "english": "One Piece",
                "native": "ワンピース"
            },
            // ... more fields
        }))
        .expect("sample anime JSON should deserialize")
    }

    #[test]
    fn anime_success_returns_embed() {
        let response = handle_anime(Some(sample_anime()), None);
        assert!(response.is_embed());
    }
}

See the #[cfg(test)] modules beside each implementation for current examples.

Code Quality Tools

Formatting with rustfmt

Format all code according to Rust style guidelines:

cargo fmt

Check formatting without modifying files:

cargo fmt -- --check

Always run cargo fmt before committing code. This is a required convention.

Linting with Clippy

Run the Clippy linter to catch common mistakes:

cargo clippy

Fix warnings automatically (when possible):

cargo clippy --fix

Treat warnings as errors:

cargo clippy -- -D warnings

Fix all Clippy warnings before committing. This ensures code quality.

Type Checking

Fast type checking without building:

cargo check

This is much faster than cargo build and catches most errors.

Code Coverage

Generate code coverage reports using cargo-tarpaulin:

Install tarpaulin

cargo install cargo-tarpaulin

Generate Coverage Report

cargo tarpaulin --out Html

This creates an HTML report at tarpaulin-report.html. For CI/CD, output in XML format:

cargo tarpaulin --out Xml

Benchmarking

Benchmark performance-critical code:

benches/fuzzy_bench.rs

use criterion::{black_box, criterion_group, criterion_main, Criterion};
use annie_mei::utils::fuzzy::fuzzy_match;

fn benchmark_fuzzy_match(c: &mut Criterion) {
    c.bench_function("fuzzy_match", |b| {
        b.iter(|| fuzzy_match(black_box("one piece"), black_box("One Piece")))
    });
}

criterion_group!(benches, benchmark_fuzzy_match);
criterion_main!(benches);

Run benchmarks:

cargo bench

Pre-Commit Workflow

Before committing, run this checklist:

Format Code

cargo fmt

Run Linter

cargo clippy

Fix all warnings.

Run Tests

cargo test --all-features

Ensure all tests pass.

Check Types

cargo check

Verify no type errors.

Consider using a git pre-commit hook to automate this workflow:

.git/hooks/pre-commit

#!/bin/sh
cargo fmt -- --check || exit 1
cargo clippy -- -D warnings || exit 1
cargo test --all-features || exit 1

Make it executable:

chmod +x .git/hooks/pre-commit

CI/CD Testing

Annie Mei uses GitHub Actions for automated testing. The workflow:

Run cargo fmt -- --check
Run cargo clippy -- -D warnings
Run cargo test --all-features
Build release binary

See .github/workflows/ for workflow definitions.

Test-Driven Development

Follow TDD for new features:

Write a Failing Test

Start with a test that captures the desired behavior:

#[test]
fn new_feature_returns_expected_value() {
    let result = new_feature("input");
    assert_eq!(result, "expected");
}

Run the Test

Verify it fails:

cargo test new_feature_returns_expected_value

Implement the Feature

Write minimal code to make the test pass:

pub fn new_feature(input: &str) -> String {
    "expected".to_string()
}

Run the Test Again

Verify it passes:

cargo test new_feature_returns_expected_value

Refactor

Improve the implementation while keeping tests green:

pub fn new_feature(input: &str) -> String {
    format!("expected: {}", input)
}

Debugging Tests

Print Debugging

Use println! or dbg! in tests:

#[test]
fn debug_example() {
    let value = compute_something();
    dbg!(&value);  // Prints file, line, and value
    assert_eq!(value, expected);
}

Run with output visible:

cargo test -- --nocapture

Test-Specific Logging

Enable logging in tests:

#[test]
fn test_with_logging() {
    let _ = tracing_subscriber::fmt::try_init();
    
    info!("Starting test");
    let result = function_under_test();
    info!("Result: {:?}", result);
    
    assert!(result.is_ok());
}

Running Single Tests in Debug Mode

RUST_BACKTRACE=1 cargo test specific_test_name -- --exact

This shows full stack traces on panics.

Best Practices

Test Naming

Use descriptive test names:

#[test]
fn ping_happy_path_returns_message_with_greeting() {
    // Test implementation
}

Format: function_scenario_expectedBehavior

Arrange-Act-Assert

Structure tests clearly:

#[test]
fn test_example() {
    // Arrange
    let input = setup_test_data();
    
    // Act
    let result = function(input);
    
    // Assert
    assert_eq!(result, expected);
}

Test Independence

Each test should be independent:

Don’t rely on test execution order
Clean up resources after tests
Avoid shared mutable state

Edge Cases

Test boundary conditions:

Empty strings
Null values (None)
Maximum/minimum values
Invalid input

Next Steps

Adding Commands

Learn how to write testable command handlers

Architecture

Understand testable design patterns

Rust Testing Book

Official Rust testing documentation

​Running Tests

​Run All Tests

​Run Specific Tests

​Show Test Output

​Writing Tests

​Unit Tests

​Test Patterns

​Integration Tests

​Live Discord smoke tests

​Mocking External APIs

​Code Quality Tools

​Formatting with rustfmt

​Linting with Clippy

​Type Checking

​Code Coverage

​Install tarpaulin

​Generate Coverage Report

​Benchmarking

​Pre-Commit Workflow

​CI/CD Testing

​Test-Driven Development

​Debugging Tests

​Print Debugging

​Test-Specific Logging

​Running Single Tests in Debug Mode

​Best Practices

Test Naming

Arrange-Act-Assert

Test Independence

Edge Cases

​Next Steps

Adding Commands

Architecture

Rust Testing Book

Running Tests

Run All Tests

Run Specific Tests

Show Test Output

Writing Tests

Unit Tests

Test Patterns

Integration Tests

Live Discord smoke tests

Mocking External APIs

Code Quality Tools

Formatting with rustfmt

Linting with Clippy

Type Checking

Code Coverage

Install tarpaulin

Generate Coverage Report

Benchmarking

Pre-Commit Workflow

CI/CD Testing

Test-Driven Development

Debugging Tests

Print Debugging

Test-Specific Logging

Running Single Tests in Debug Mode

Best Practices

Next Steps