Testing Applications

Relevant source files

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

• DEVELOPMENT.md
• CONTRIBUTING.md
• loco-new/tests/wizard/new.rs
• loco-new/tests/templates/db.rs
• tests/build_scripts/embedded_assets.rs
• docs-site/content/casts/005-testing-tasks.md

Testing in the Loco framework is designed to be a "batteries-included" experience, allowing developers to validate models, controllers, background jobs, and tasks with minimal effort. The framework emphasizes a test-driven approach to ensure application stability and performance while maintaining the high-speed delivery characteristic of the "one-person framework" philosophy.

The testing infrastructure supports various levels of validation, ranging from unit tests for generated code and assets to comprehensive integration tests that exercise the CLI, database migrations, and full application flows. Developers are encouraged to use built-in tools like cargo loco doctor and snapshot testing to maintain confidence throughout the development lifecycle.
Sources: docs-site/content/_index.md:52-53, CONTRIBUTING.md:79-81

Testing Workflow and Requirements

Loco applications require specific environmental components to be active before running the test suite. This typically includes a running Redis instance and, for certain starters, a built frontend package. The framework provides a centralized command via xtask to streamline the execution of all tests.

Pre-requisites for Testing

• Redis: Must be running for background job testing.
• Frontend: For SaaS starters, the frontend must be built (e.g., via pnpm build).
• Environment: The LOCO_ENV variable or specific flags like --environment test are used to isolate testing configurations.

Sources: DEVELOPMENT.md:20-30, DEVELOPMENT.md:39-41

Snapshot Testing

Loco utilizes insta for snapshot testing, which captures the output of various components (like generated file structures or CLI responses) and compares them against stored "gold master" files. This is particularly useful for detecting unintended changes in output formats or logic behavior.

CLI and Output Validation

For CLI-specific changes, Loco uses trycmd to overwrite and review binary command outputs. Developers can review these snapshots using the cargo insta CLI tool.

Test Type	Tool Used	Purpose
UI/Format Snapshots	insta	Detect changes in generated templates and text output
CLI Snapshots	trycmd	Validate binary command output and interactions
Data Snapshots	insta	Verify serialized data structures and database configurations

Sources: CONTRIBUTING.md:83-93, loco-new/tests/templates/db.rs:27-37

Integration and Template Testing

The framework includes extensive tests for its internal generators and templates to ensure that the code provided to end-users is functional and follows best practices.

Generator Validation

Testing the generator involves creating a temporary file system, running the generator with specific settings (e.g., SQLite vs Postgres, Auth enabled vs disabled), and performing assertions on the resulting files. The TestGenerator utility is used to facilitate these tests by managing the lifecycle of generated test projects.
Sources: loco-new/tests/wizard/new.rs:43-58, loco-new/tests/templates/db.rs:8-15

Code Snippet: Asserting Template Configuration

#[rstest]
fn test_config_file_no_db(
    #[values("config/development.yaml", "config/test.yaml")] config_file: &str,
) {
    let generator = run_generator(DBOption::None);
    let content = assertion::yaml::load(generator.path(config_file));
    assertion::yaml::assert_path_is_empty(&content, &["database"]);
}

Sources: loco-new/tests/templates/db.rs:18-24

Testing Components

Task Testing

Tasks in Loco are linear business workflows that have access to the full AppContext. Testing them involves providing specific inputs and asserting the resulting side effects or outputs.
Sources: docs-site/content/casts/005-testing-tasks.md:2-4

Embedded Assets

Build scripts for embedded assets are tested by creating a mock tree of files (e.g., CSS, JS, HTML) and verifying that the generation of static_assets.rs and view_templates.rs correctly maps the file system to internal Rust code.
Sources: tests/build_scripts/embedded_assets.rs:20-30, tests/build_scripts/embedded_assets.rs:40-58

Diagnostic Tools

The loco doctor command serves as a runtime validation tool that can be used during testing to ensure the environment is correctly configured. It checks for:

• SeaORM CLI installation
• Database connectivity
• Redis connectivity
• Correct environment loading

Sources: DEVELOPMENT.md:4-15, CONTRIBUTING.md:42-45

Summary

Testing applications within the Loco ecosystem is a multi-layered process that ensures both the framework's internal generators and the user's end-application remain robust. By leveraging snapshot testing and built-in diagnostic tools, Loco provides a high-confidence environment for rapid development.
Sources: docs-site/content/_index.md:52-53, CONTRIBUTING.md:120-130