Testing & CI Validation

Relevant source files

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

• progress.md
• README.md
• claude/CLAUDE.md
• packaging/README.md
• crates/gtk-app/src/main.rs
• crates/gtk-app/src/projects.rs
• crates/gtk-app/src/session_surface.rs

Testing and CI Validation in the Linux Archductor project provide a rigorous multi-layered verification framework to ensure the stability of the agent-control plane. This includes static analysis (formatting and linting), unit testing of core pseudo-terminal (PTY) parsing logic, and specialized release readiness gates that automate the transition from local development to multi-distribution packaging.

The project follows a Linux-first quality stance, utilizing automated scripts and manual checklists to validate workflows across Core, CLI, and GTK interfaces. Specific attention is given to the PTY-backed harness model, ensuring that structured transcript events and session state machines remain accurate across updates.

Sources: progress.md:1-25, README.md:144-155, claude/CLAUDE.md:118-124

Release Readiness Framework

The project utilizes a dedicated release readiness phase to gate public distributions. This process is automated via scripts/release-readiness.sh, which performs a sequence of checks to ensure the codebase meets quality standards before artifacts are generated.

Automated Readiness Gates

The readiness script executes the following stages:

1. Formatting: Runs cargo fmt --all -- --check to enforce consistent style.
2. Linting: Executes cargo clippy --workspace --all-targets --locked -- -D warnings to treat lints as errors.
3. Testing: Runs the full workspace test suite via cargo test --workspace.
4. Security/Audit: Executes cargo deny check when available to validate dependencies.
5. Release Build: Compiles release-mode binaries for all crates.
6. Packaging: Optionally generates local package artifacts and associated checksums.

Sources: progress.md:329-338, packaging/README.md:27-31

Release Readiness Flow

The following diagram illustrates the automated gate sequence required for a release:

Testing Layers

Verification is divided into three primary categories based on the crate architecture: Core, CLI, and GTK.

Core Logic Verification

Core testing focuses on state persistence (SQLite), Git worktree operations, and PTY log parsing. Key verification paths include:

• Session State Machine: Validates transitions between starting, running, streaming, failed, and exited states.
• PTY Parser Corpus: Uses a fixture corpus to verify the accuracy of the Codex TUI parser and structured transcript generation.
• Workspace Lifecycle: Tests for creation, duplication, renaming, and archiving.

GTK App Verification

The GTK application requires display-aware verification. These tests are often performed in a Linux VM (e.g., Lima/Ubuntu) using VNC displays to prove the app can launch and maintain its lifecycle.

• View Preferences: Validates the application of CSS classes for themes, accent colors, and density.
• Session Surface: Tests the rendering of app-native transcript events from raw PTY logs.
• Launch Targets: Validates deep link parsing (e.g., linux-archductor://workspace/berlin?tab=checks).

Sources: progress.md:52-78, crates/gtk-app/src/main.rs:777-832, crates/gtk-app/src/session_surface.rs:1360-1410

Test Command Matrix

Scope	Command	Description
Full Workspace	cargo test --workspace	Standard suite for all crates.
Core Library	cargo test -p linux-archductor-core --lib	Logic for Git, SQLite, and parsing.
PTY Parsing	cargo test -p linux-archductor-core --test pty_parser_fixture_corpus	Accuracy of TUI-to-structured events.
GTK UI	cargo test -p linux-archductor-gtk	Logic for tabs, themes, and form mapping.
CLI Logic	cargo test -p linux-archductor --test cli_sessions	Real shell session lifecycle via CLI.

Sources: progress.md:25-36, progress.md:52-65

CI & Publishing Pipeline

The project uses GitHub Actions for automated building and publishing. The pipeline is designed to be tag-driven to ensure repeatability and semantic versioning.

Multi-Distribution Publishing

Archductor publishes to all supported Linux package channels:

• Native Packages: .deb (APT), .rpm (DNF/zypper), and AUR (Arch Linux).
• Universal Packages: AppImage and Flatpak.
• GitHub Releases: Tarball artifacts and checksums.

Verification Flow for CI

The diagram below details the interaction between the CI pipeline and the publishing gates:

Runtime & Lifecycle Verification

The GTK application includes specialized internal testing for runtime state reconciliation. This ensures that stale processes are cleaned up and the UI accurately reflects the state of the background services.

Runtime Reconciliation

The app triggers reconciliation on startup, window focus, and file events. This logic is verified via unit tests within the GTK crate to ensure stale terminal rows are marked as exited if their corresponding PIDs are no longer active.

// Example of runtime reconciliation test logic in crates/gtk-app/src/main.rs
#[test]
fn startup_runtime_reconciliation_marks_stale_terminal_rows_exited() {
    // ... setup repo and db ...
    store.record_terminal_process("berlin", "shell", 999_999).unwrap();
    let report = reconcile_runtime_state(&db_path).unwrap();
    assert_eq!(report.terminal_processes_reconciled, 1);
}

Sources: crates/gtk-app/src/main.rs:777-805

Source Preflight Checks

Before workspace creation, the system performs "preflight" checks on external dependencies.

• GitHub Status: Verifies gh CLI installation and authentication state.
• Linear Status: Checks for the presence of the LINEAR_API_KEY.
  Tests in projects.rs verify that these states are accurately summarized for the user.

Sources: crates/gtk-app/src/projects.rs:1041-1052, progress.md:83-88

Testing and CI Validation in Archductor serves as a gate for the complex interactions between agent-driven code modification and Git-based isolation. By combining automated readiness scripts with deep-link and PTY-parser validation, the project maintains a reliable desktop environment for parallel coding tasks.