Testing Strategy

Relevant source files

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

• AGENTS.md
• src/config.rs
• src/diff.rs
• src/template/frontmatter.rs
• src/template/render.rs
• src/template/versions.rs
• src/main.rs

Orcastrate implements a multi-layered testing strategy to ensure the reliability of GitHub Actions workflow orchestration. The strategy combines local unit tests for core logic, configuration validation, and template rendering checks to prevent invalid workflows from being deployed to managed repositories.

The project utilizes Rust's built-in testing framework for unit tests and leverages external tools for CI/CD validation. You can execute the test suite locally using the cargo test command.

Sources: AGENTS.md:46-49, AGENTS.md:52-53

Unit Testing Architecture

Orcastrate maintains a suite of unit tests distributed across core modules. These tests verify the isolated logic of configuration parsing, frontmatter extraction, diff generation, and action version preservation.

Core Test Modules

Module	Testing Focus
config	Validates orchestrator.toml parsing, repo format requirements, and default values.
frontmatter	Ensures correct extraction of Tera templates and parameters from YAML comments.
diff	Verifies drift detection logic and unified diff generation accuracy.
template::versions	Validates the preservation of action tags and SHA pins during rendering.
template::render	Confirms Tera rendering output matches expected YAML structures.

Sources: AGENTS.md:48-49, src/config.rs:100-118, src/diff.rs:44-71, src/template/frontmatter.rs:75-125, src/template/versions.rs:136-218

Logic Flow for Version Preservation Tests

The following diagram illustrates how the preserve_action_versions logic is tested to ensure template rendering does not overwrite existing specific action versions.

The logic matches action references by job name, step ID, or occurrence order to maintain consistency.
Sources: src/template/versions.rs:88-134

Configuration and Template Validation

Orcastrate provides built-in commands to validate the environment and assets before performing any sync operations. This prevents runtime errors during scheduled executions.

Validation Logic

• Config Validation: The Config::load function calls an internal validate() method. It checks if at least one repository or discovery method is defined and ensures repository names follow the owner/repo format.
• Template Validation: The TemplateRenderer validates rendered output by attempting to parse it as YAML. If the rendered template produces invalid YAML, the renderer returns a YamlValidation error.
• Manual Validation: You can run orcastrate validate to check the current configuration and list all successfully loaded templates.

Sources: src/config.rs:59-78, src/template/render.rs:64-71, src/main.rs:71-84

Workflow Rendering Verification

The Render command allows for offline verification of managed workflows. This command renders a local workflow file to stdout without requiring GitHub API credentials.

// src/main.rs:46-51
Command::Render { workflow } => {
    let config = Config::load(&cli.config)?;
    let renderer = TemplateRenderer::new(Path::new(&config.orchestrator.templates_dir))?;
    let content = std::fs::read_to_string(workflow)?;
    print!("{}", renderer.render_workflow(&content)?);
}

This testing path is used to pipe output to external tools like actionlint for deep syntax checking of the generated GitHub Actions YAML.

Sources: src/main.rs:46-51, README.md:120-125

Drift Detection Testing

The drift detection module is tested to ensure it correctly identifies changes between the current repository state and the canonical template.

Tests verify that identical content results in no drift, while any character change triggers a detection.
Sources: src/diff.rs:3-33, src/diff.rs:47-70

CI/CD Integration

The project uses GitHub Actions to automate the testing process. The CI pipeline performs the following actions on every push:

1. Builds the Rust binary.
2. Runs the full unit test suite via cargo test.
3. Checks code style and linting with clippy.
4. Publishes Docker images to GHCR only if all previous steps pass.

Sources: AGENTS.md:52-57

Conclusion

Orcastrate emphasizes "safety-first" sync operations. By combining strict YAML validation in the rendering engine, unit tests for complex regex/string manipulation in version preservation, and a dry-run mode for end-to-end simulation, the system ensures that automated PRs do not break downstream repository workflows.

Sources: src/template/render.rs:64-71, src/template/versions.rs:136-150, AGENTS.md:27-33