Testing Strategies

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• DEVELOPMENT.md
• src/docs.rs
• sea-orm-sync/src/docs.rs
• sea-orm-sync/CLAUDE.md
• CLAUDE.md

SeaORM utilizes a multi-tiered testing strategy to ensure the reliability of its ORM capabilities across different database backends and execution environments. This strategy encompasses unit testing with mock databases, integration testing against live database instances, and specialized handling for synchronous vs. asynchronous execution modes.

The primary goal is to provide developers with a "testable" framework where application logic can be verified without a live database dependency using MockDatabase, while still supporting robust end-to-end validation through Docker-managed database environments.
Sources: src/docs.rs:108-110, CONTRIBUTING.md:46-77

Unit Testing with Mocking

Unit testing in SeaORM is designed to be performed without involving a live database. This is achieved through the MockDatabase component, which allows developers to simulate database responses and verify the resulting transaction logs.
Sources: src/docs.rs:112-114, CONTRIBUTING.md:46-48

Mock Database Workflow

When using a mock connection, the developer pre-configures expected query results. The application logic interacts with this mock as if it were a real DbConn. After execution, the developer asserts that the generated SQL and values match the expected Transaction log.
Sources: src/docs.rs:114-142, sea-orm-sync/src/docs.rs:88-116

The diagram above illustrates the lifecycle of a unit test using the mocking system to verify both output data and internal SQL generation.
Sources: src/docs.rs:115-141

Key Mocking Components

Component	Description
MockDatabase	The entry point for creating a mock connection. Supports various DbBackend types (Postgres, MySQL, SQLite).
append_query_results	A method to queue up arrays of model data that will be returned sequentially by the mock.
into_mock_row	A trait method to convert a Model instance into a format compatible with mock responses.
Transaction	A structure used to verify the SQL string and parameters executed against the mock.
Sources: src/docs.rs:115-141, sea-orm-sync/src/docs.rs:14-41

Integration Testing

Integration tests validate SeaORM's behavior against real database engines. These tests require specific environment variables and feature flags to target different backends.
Sources: CONTRIBUTING.md:58-61, DEVELOPMENT.md:33-38

Database Environment Setup

The project recommends using Docker to spawn database instances for testing. A docker-compose.yml is provided in build-tools, and specific container startup commands are documented for PostgreSQL 14.
Sources: CONTRIBUTING.md:61-63, DEVELOPMENT.md:23-31

Execution Commands

Integration tests are typically executed using cargo test with defined DATABASE_URL strings and backend-specific driver features.
Sources: CONTRIBUTING.md:65-77, DEVELOPMENT.md:33-38

Backend	Example Command	Required Features
SQLite	DATABASE_URL="sqlite::memory:" cargo test	sqlx-sqlite, runtime-tokio (or async-std)
MySQL	DATABASE_URL="mysql://root:root@localhost" cargo test	sqlx-mysql, runtime-tokio-native-tls
PostgreSQL	DATABASE_URL="postgres://root:root@localhost" cargo test	sqlx-postgres, runtime-tokio-native-tls
Sources: CONTRIBUTING.md:65-77, DEVELOPMENT.md:33-38

Testing Synchronous vs. Asynchronous Code

SeaORM maintains two versions of the crate: the standard async version and sea-orm-sync. Testing strategies differ slightly to accommodate these paradigms.
Sources: sea-orm-sync/CLAUDE.md:1-25

Sync Crate Generation and Validation

Code in sea-orm-sync is generated from the root src/ and tests/ directories via a transform script (make-sync.sh). Tests for the sync version must be run within the sea-orm-sync directory after regeneration.
Sources: sea-orm-sync/CLAUDE.md:6-14

This flow ensures that test logic remains consistent between async and sync versions while adapting to technical constraints like the rusqlite backend.
Sources: sea-orm-sync/CLAUDE.md:1-25

Specialized Test Macros

The project uses #[sea_orm_macros::test] to gate tests based on available features. In the sync crate, this macro specifically gates tests on the rusqlite feature, whereas the async crate gates on various sqlx-* features.
Sources: sea-orm-sync/CLAUDE.md:21-25

Development Workflow and Quality Assurance

Before submitting a Pull Request (PR), contributors are expected to follow a strict validation checklist to maintain code quality.
Sources: DEVELOPMENT.md:1-21

1. Formatting: Run cargo +nightly fmt. If nightly is unavailable, contributors must at least run cargo fmt and restore specific generated directories like sea-orm-codegen/src/tests_cfg/.
2. Linting: Run cargo clippy --all using the latest stable clippy.
3. Unit Tests: Execute cargo test --lib for library logic and cargo test --doc to verify documentation examples.
4. Local Patching: For testing SeaORM changes within another local project, a [patch.crates-io] entry in Cargo.toml is recommended.
   Sources: DEVELOPMENT.md:1-21

Conclusion

Testing in SeaORM is a tiered process that prioritizes developer productivity through a robust mocking system while ensuring cross-database compatibility via comprehensive integration test suites. By strictly separating mock verification from live database validation, the project allows for rapid iteration of application logic with high confidence in the generated SQL output.
Sources: src/docs.rs:108-142, CONTRIBUTING.md:46-77