How to Test bitchat: Complete Guide to Swift Package, iOS Simulator, and Performance Testing

Run bitchat tests using swift test for core packages, just test for convenience shortcuts, or xcodebuild with iOS Simulator for full UI integration testing.

The bitchat application from permissionlesstech provides multiple testing layers covering its Swift Package Manager (SPM) core libraries, iOS/macOS UI components, and performance benchmarks. This guide walks through each testing method as implemented in the permissionlesstech/bitchat repository.

Swift Package Manager Tests for Core Libraries

The foundation of bitchat testing targets the BitLogger and BitFoundation packages located in localPackages/. These are pure Swift tests executed via SPM.

Running SPM Tests Manually

According to the Build & Test workflow, the CI uses this command structure:

swift test --skip-build --parallel --quiet --enable-code-coverage \
           --skip PerformanceBaselineTests --package-path <path>

The --package-path parameter supports three matrix targets:

• . — the full application
• localPackages/BitLogger — logging subsystem tests
• localPackages/BitFoundation — cryptographic and protocol tests

Test File Locations

Key test suites are organized under their respective package directories:

• localPackages/BitLogger/Tests/* — logging functionality validation
• localPackages/BitFoundation/Tests/* — core utilities including BinaryProtocolTests.swift

Just Command Shortcuts for Local Testing

The repository includes a Justfile that wraps complex test commands into simple shortcuts. Install just first:

brew install just

Then use these commands to test bitchat locally:

Command	Purpose
just test	Run SPM test suite for all packages
just test-ios	Build iOS target and run simulator-based tests

The just test command mirrors the CI matrix jobs, while just test-ios reproduces the iOS tests job locally.

iOS Simulator Integration Tests

For UI-level validation, bitchat uses xcodebuild with dynamic simulator selection. The CI workflow demonstrates the exact configuration with these parameters:

xcodebuild -project bitchat.xcodeproj \
          -scheme "bitchat (iOS)" \
          -sdk iphonesimulator \
          -destination "platform=iOS Simulator,name=iPhone 14" \
          CODE_SIGNING_ALLOWED=NO test

The CODE_SIGNING_ALLOWED=NO flag enables testing without developer certificate setup. The workflow dynamically selects available iPhone simulators to match CI environment capabilities.

Performance Baseline Testing

Benchmark tests are excluded from normal runs via BITCHAT_SKIP_PERF_BASELINES=1 and the --skip PerformanceBaselineTests flag. To execute performance tests specifically:

swift test --quiet --filter PerformanceBaselineTests

After running, the CI validates results against floor files using scripts/check-perf-floors.sh. This script Compares measured performance against established baselines to catch regressions.

Code Coverage Reporting

The bitchat CI generates coverage reports using llvm-cov. Reproduce this locally with:

BIN_PATH=$(swift build --show-bin-path --package-path .)
PROF="$BIN_PATH/codecov/default.profdata"
XCTEST=$(find "$BIN_PATH" -maxdepth 1 -name '*.xctest' | head -1)
BINARY="$XCTEST/Contents/MacOS/$(basename "$XCTEST" .xctest)"
xcrun llvm-cov report "$BINARY" -instr-profile "$PROF"

This extracts the profiling data from Swift's build artifacts and produces a human-readable coverage summary.

Additional Test Suites

Beyond the core Swift tests, bitchat includes validation scripts in the scripts/tests/ directory:

• scripts/tests/test_validate_georelays.py — Python validation for georelay functionality
• scripts/tests/test_fetch_georelays_workflow.py — orchestration tests for the fetch_georelays.yml workflow

These are invoked by the separate Fetch Georelays workflow rather than the main test suite.

Summary

• Core testing uses swift test with --enable-code-coverage and parallel execution for BitLogger and BitFoundation packages
• Convenience commands via just test and just test-ios simplify local reproduction of CI behavior
• iOS integration requires xcodebuild with iphonesimulator SDK and explicit destination targeting
• Performance baselines run separately with --filter PerformanceBaselineTests and validate via scripts/check-perf-floors.sh
• Coverage reports generate through llvm-cov integration with Swift's built-in profiling

Frequently Asked Questions

What testing framework does bitchat use?

bitchat uses XCTest through Swift Package Manager for all test targets. The core packages in localPackages/ contain standard XCTest cases, while the iOS application uses XCTest for UI integration testing via simulator.

How do I run tests without an Apple Developer account?

Use CODE_SIGNING_ALLOWED=NO in your xcodebuild commands, as shown in the iOS simulator example. The just test and just test-ios shortcuts also handle this automatically for local development.

Why are performance tests skipped by default?

Performance baselines require stable hardware to produce comparable results. The CI excludes them from standard runs using --skip PerformanceBaselineTests or the BITCHAT_SKIP_PERF_BASELINES=1 environment variable. Run them explicitly when validating performance-critical changes.

Where does bitchat store its CI test configuration?

All GitHub Actions workflows live in .github/workflows/. The primary test configuration is swift-tests.yml, which defines the matrix jobs for SPM tests, iOS simulator tests, coverage collection, and performance validation.

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