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

> Learn how to test the bitchat app using swift test, just test, or xcodebuild with iOS Simulator. Master package, simulator, and performance testing for robust applications.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: testing
- Published: 2026-08-20

---

**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](https://github.com/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**](https://github.com/permissionlesstech/bitchat/blob/main/.github/workflows/swift-tests.yml), the CI uses this command structure:

```bash
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`](https://github.com/permissionlesstech/bitchat/blob/main/BinaryProtocolTests.swift)

## Just Command Shortcuts for Local Testing

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

```bash
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](https://github.com/permissionlesstech/bitchat/blob/main/.github/workflows/swift-tests.yml#L84-L86) 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:

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

```bash
swift test --quiet --filter PerformanceBaselineTests

```

After running, the CI validates results against floor files using [`scripts/check-perf-floors.sh`](https://github.com/permissionlesstech/bitchat/blob/main/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:

```bash
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`](https://github.com/permissionlesstech/bitchat/blob/main/scripts/tests/test_validate_georelays.py) — Python validation for georelay functionality
- [`scripts/tests/test_fetch_georelays_workflow.py`](https://github.com/permissionlesstech/bitchat/blob/main/scripts/tests/test_fetch_georelays_workflow.py) — orchestration tests for the [`fetch_georelays.yml`](https://github.com/permissionlesstech/bitchat/blob/main/fetch_georelays.yml) workflow

These are invoked by the separate [**Fetch Georelays workflow**](https://github.com/permissionlesstech/bitchat/blob/main/.github/workflows/fetch_georelays.yml) 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`](https://github.com/permissionlesstech/bitchat/blob/main/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**](https://github.com/permissionlesstech/bitchat/blob/main/.github/workflows/swift-tests.yml), which defines the matrix jobs for SPM tests, iOS simulator tests, coverage collection, and performance validation.