# How to Test CodexBar Functionality: Unit and Integration Testing Guide

> Learn to test CodexBar functionality effectively with our guide on unit and integration testing. Discover strategies for logic validation and app verification for the steipete/CodexBar repository.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: testing
- Published: 2026-07-10

---

**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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/StatusMenuSwitcherLayoutTests.swift) – Validates the visual layout algorithms for the status-menu switcher.
- [`Tests/CodexBarTests/UsageStorePlanUtilizationTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/UsageStorePlanUtilizationTests.swift) – Verifies the plan-quota mapping algorithms that drive usage bar calculations.
- [`Tests/CodexBarTests/SyntheticProviderTests.swift`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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:

```bash
make test

```

This invokes [`Scripts/test_sharding.sh`](https://github.com/steipete/CodexBar/blob/main/Scripts/test_sharding.sh), which parallelizes the 150+ test cases across available CPU cores to minimize CI times.

Run tests for a specific component:

```bash
swift test --filter StatusMenuSwitcherLayoutTests

```

Filter by test name pattern:

```bash
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:

```bash
./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`](https://github.com/steipete/CodexBar/blob/main/StatusMenuOpenRefreshTests.swift)

Skip UI tests if you encounter flaky interface elements:

```bash
./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`](https://github.com/steipete/CodexBar/blob/main/TestStores.swift) file provides mock implementations of production protocols.

**Example test structure** from [`Tests/CodexBarTests/SyntheticProviderTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/SyntheticProviderTests.swift):

```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:

```bash
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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/Scripts/compile_and_run.sh) script provides a `--skip-ui` flag that bypasses tests requiring live menu-bar interaction. If [`StatusMenuOpenRefreshTests.swift`](https://github.com/steipete/CodexBar/blob/main/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.