artcraft/.claude/rules/testing.md

Testing

Database Fixture Tests

• Live in-crate (e.g. storyteller-web's omni_gen video pricing tests) and use the mysql_testing crate (crates/schema/database/mysql_testing) for guarded pools, schema setup, and account/session/wallet fixtures
• They RUN BY DEFAULT with cargo test -p storyteller-web and from the IDE (requires a local MySQL with an artcraft_test database). Machines/CI without MySQL skip them via the off switch: SQLX_OFFLINE=true cargo test -p storyteller-web --features skip_database_tests
• They connect ONLY via ARTCRAFT_TEST_DATABASE_URL (default mysql://root:@localhost:3306/artcraft_test); the guard panics on any database whose name lacks "test", on storyteller/artcraft, and on cloud hosts — see mysql_testing/README.md
• Database tests run in PARALLEL: each test creates its own users, wallets, and rows; schema setup single-flights via a MySQL named lock. Only tests mutating shared/global state take mysql_testing::serial::acquire_serial_test_lock().await
• External providers must never be called: the harness stubs Kinovi with an in-process HTTP server via KINOVI_CUSTOM_API_HOST/KINOVI_CUSTOM_CDN_HOST

Running Tests

• Most crates: cargo test -p {crate_name}
• Crates using SQLx offline mode: SQLX_OFFLINE=true cargo test -p {crate_name}
• The storyteller-web and mysql_queries crates require SQLX_OFFLINE=true for compilation
• Use cargo check -p {crate_name} for fast compilation checks without running tests

Test Patterns

• Tests live in #[cfg(test)] mod tests { ... } at the bottom of each file
• Group related tests into sub-modules by category (e.g. mod pricing_tests, mod resolution_tests)
• Only create a sub-module when it has 2+ tests — don't wrap a single test in its own module
• Keep nesting shallow: mod tests { mod category { ... } } is fine; a third level is rarely needed
• Shared helpers used by multiple sub-modules belong in the parent mod tests, not duplicated in each sub-module
• Enum tests should cover: serialization, deserialization, to_str/from_str round-trip, variant count
• Password/crypto tests: be mindful of computation cost, don't add too many bcrypt test cases

Test File Layout

Put test cases first, helpers last. Engineers should see the actual tests before scrolling to understand helper plumbing.

Within a mod tests { ... } block:

1. Imports at the top
2. Constants (test data IDs, URLs, etc.) — small context that tests reference
3. Test functions (#[test] / #[tokio::test]) grouped by category
4. Helper functions (builders, pipeline runners, etc.) at the very bottom

If tests are grouped into sub-modules, the same rule applies within each sub-module: constants first, then tests, then helpers at the end of that sub-module.

What to Test

• New error types and their mappings
• Enum variant serialization stability (these are stored in the database)
• Hash/deduplication functions with known inputs
• Edge cases in parsers (empty input, missing fields, malformed data)

Imports in Tests

• Import test fixtures and constants with use, not inline fully-qualified paths. Write use test_data::web::image_urls::JUNO_AT_LAKE_IMAGE_URL; at the top, then reference JUNO_AT_LAKE_IMAGE_URL in test bodies.
• Same rule applies to enum variants used in match arms — import them, don't write crate::some::deep::module::MyEnum::Variant inline.

What Not to Test

• Don't add integration tests that require a running database unless explicitly asked
• Don't add tests for simple struct construction or trivial getters