How to Test CodexBar Functionality: Unit and Integration Testing Guide

CodexBar uses a sharded two-tier testing strategy where swift test executes over 150 isolated XCTest cases for logic validation, while ./Scripts/compile_and_run.sh --test launches the full macOS app to verify menu-bar rendering and external process interactions.

CodexBar is a SwiftPM-based macOS menu-bar application for monitoring OpenAI Codex usage. Understanding how to test CodexBar functionality ensures reliable parsing, state management, and UI rendering across macOS versions. The test suite leverages dependency injection and mock objects to isolate components, providing fast feedback during development and comprehensive coverage in CI.

Testing Architecture Overview

The test suite is organized into distinct layers that mirror the production codebase structure defined in Package.swift.

Unit Test Target

The CodexBarTests target contains focused XCTest cases that verify core logic without launching the full application. Key test files include:

• Tests/CodexBarTests/StatusMenuSwitcherLayoutTests.swift – Validates the visual layout algorithms for the status-menu switcher.
• Tests/CodexBarTests/UsageStorePlanUtilizationTests.swift – Verifies the plan-quota mapping algorithms that drive usage bar calculations.
• Tests/CodexBarTests/SyntheticProviderTests.swift – Tests provider logic using deterministic synthetic data.

These tests rely on dependency injection through mock implementations defined in Tests/CodexBarTests/TestStores.swift, including FakeNetworkFetcher, mock TokenAccountStore, and ProcessRunner stubs.

Integration Test Harness

Integration tests exercise the complete app bundle, including the CodexBarCLI tool and WidgetExtension. The harness in Scripts/compile_and_run.sh orchestrates:

• Release builds via swift build -c release
• Process lifecycle management (killing existing instances)
• Live menu-bar interaction testing
• Snapshot validation for macOS widgets

Running Unit Tests Locally

Execute the sharded unit test suite using the standard Swift Package Manager workflow.

Prerequisites: Ensure Xcode 15+ or the corresponding Swift toolchain is installed. The project requires only standard library and Apple frameworks—no external package dependencies.

Run the full test suite:

make test

This invokes Scripts/test_sharding.sh, which parallelizes the 150+ test cases across available CPU cores to minimize CI times.

Run tests for a specific component:

swift test --filter StatusMenuSwitcherLayoutTests

Filter by test name pattern:

swift test --filter UsageParserTests

Executing Integration and UI Tests

Full application testing requires launching the live menu-bar app to validate status-item lifecycle and external-process interactions.

Run the complete integration suite:

./Scripts/compile_and_run.sh --test

This script performs the following operations:

1. Compiles the release app bundle
2. Terminates any running CodexBar processes
3. Launches CodexBar.app in a fresh instance
4. Executes XCTest cases that interact with the live menu bar, including StatusMenuOpenRefreshTests.swift

Skip UI tests if you encounter flaky interface elements:

./Scripts/compile_and_run.sh --test --skip-ui

Test Implementation Patterns

The suite follows a consistent pattern of dependency injection to isolate units under test. The TestStores.swift file provides mock implementations of production protocols.

Example test structure from Tests/CodexBarTests/SyntheticProviderTests.swift:

import XCTest
@testable import CodexBar

final class SyntheticProviderTests: XCTestCase {
    func testSyntheticUsageIsParsedCorrectly() async throws {
        // Arrange – inject a fake network fetcher returning deterministic JSON
        let fakeFetcher = FakeNetworkFetcher(json: """
        {"usage": 123, "plan": "pro"}
        """)
        
        // Act – invoke the usage fetcher with the mock dependency
        let usage = try await UsageFetcher(fetcher: fakeFetcher).fetch()
        
        // Assert – verify the parsed model matches expectations
        XCTAssertEqual(usage.amount, 123)
        XCTAssertEqual(usage.plan, .pro)
    }
}

Test the CLI tool independently using synthetic providers:

codexbar usage --provider synthetic --detail

Summary

• Unit tests validate parsing, state management, and provider logic in isolation via swift test or make test, executing over 150 XCTest cases with heavy reliance on mocks from TestStores.swift.
• Integration tests require ./Scripts/compile_and_run.sh --test to build the full app bundle and verify menu-bar rendering, status-item lifecycle, and CLI behavior.
• Test sharding across CPU cores keeps CI execution times low while maintaining comprehensive coverage.
• Dependency injection patterns in Tests/CodexBarTests/ allow precise control over NetworkFetcher, TokenAccountStore, and ProcessRunner dependencies.

Frequently Asked Questions

How do I run only specific test cases in CodexBar?

Use the --filter flag with swift test to target specific test classes or methods. For example, swift test --filter StatusMenuSwitcherLayoutTests runs only the layout validation tests, while swift test --filter UsageStorePlanUtilizationTests isolates the plan-quota algorithm checks.

What macOS version and tools are required to test CodexBar?

You need Xcode 15 or later (or the matching Swift toolchain). The project uses only the standard library and Apple frameworks—no additional package managers or third-party dependencies are required. The test suite targets macOS menu-bar APIs available in recent platform versions.

How does CodexBar handle flaky UI tests?

The Scripts/compile_and_run.sh script provides a --skip-ui flag that bypasses tests requiring live menu-bar interaction. If StatusMenuOpenRefreshTests.swift or similar UI-dependent tests fail intermittently due to system animation timing, re-run the suite with this flag to execute only the stable unit and CLI tests.

Can I test the CodexBar CLI independently from the GUI?

Yes. The codexbar command-line tool defined in Sources/CodexBarCLI/ accepts a --provider synthetic argument that feeds deterministic test data without requiring network access or the full app bundle. This allows validation of usage parsing and output formatting in isolation using the same mock infrastructure as the unit tests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}