Testing and Quality Assurance

Relevant source files

• .github/workflows/swift-tests.yml
• .periphery.yml
• .swiftlint.yml
• Package.swift
• bitchat/Services/TestEnvironment.swift
• bitchatTests/BLEServiceTests.swift
• bitchatTests/EndToEnd/PrivateChatE2ETests.swift
• bitchatTests/EndToEnd/PublicChatE2ETests.swift
• bitchatTests/Integration/IntegrationTests.swift
• bitchatTests/Mocks/MockBLEService.swift
• bitchatTests/TestUtilities/TestConstants.swift
• bitchatTests/TestUtilities/TestHelpers.swift
• scripts/check-perf-floors.sh

This page provides an overview of the testing architecture, CI/CD integration, and quality assurance strategies for the BitChat codebase. It covers the in-memory networking harness used to make decentralized protocol testing deterministic and the automated workflows ensuring code quality.

For deep dives into specific testing areas, see the following child pages:

• Test Architecture and Coverage — Document test targets, dependency injection for testability (e.g., TestEnvironment detection), and the swift test workflow.
• Protocol and Cryptography Testing — Detail NostrProtocolTests, cryptography verification (Noise handshakes), and protocol compliance validation.
• Transport and Integration Tests — Explain BLEServiceTests, MeshTopologyTrackerTests, and integration testing strategies.

---

Test Architecture Overview

BitChat utilizes the Swift Testing framework for modern, async-native validation. The suite is designed to be deterministic and race-free by using an in-memory bus (MockBLEBus) that replaces physical Bluetooth hardware during test execution [bitchatTests/Mocks/MockBLEService.swift:30-30]. Global test detection is handled by TestEnvironment, which identifies when the app is running under XCTest, Swift Testing, or CI environments [bitchat/Services/TestEnvironment.swift:15-25].

Core Test Components

Component	Role in Testing	Code Entity
In-Memory Bus	Central exchange for simulated packet delivery	MockBLEBus [bitchatTests/Mocks/MockBLEService.swift:30-30]
Mock Service	Test-double for BLEService	MockBLEService [bitchatTests/Mocks/MockBLEService.swift:29-29]
Topology Manager	Controls peer links and adjacency	MockBLEBus.neighbors(of:) [bitchatTests/Mocks/MockBLEService.swift:69-71]
Test Helper	Orchestrates multi-node networks	TestNetworkHelper [bitchatTests/Integration/IntegrationTests.swift:17-17]

The testing suite is divided into three primary layers:

1. Unit Tests: Focused on isolated logic like BLEService initialization and peer connection state [bitchatTests/BLEServiceTests.swift:27-42].
2. Integration Tests: Validating multi-peer scenarios, dynamic topology changes, and network partition recovery [bitchatTests/Integration/IntegrationTests.swift:28-85].
3. End-to-End (E2E) Tests: Simulating full message lifecycles, including private message encryption via NoiseSessionManager [bitchatTests/EndToEnd/PrivateChatE2ETests.swift:112-127].

Sources: [bitchatTests/Mocks/MockBLEService.swift:29-45], [bitchatTests/Integration/IntegrationTests.swift:15-24], [bitchatTests/BLEServiceTests.swift:14-23], [bitchat/Services/TestEnvironment.swift:15-25]

---

CI/CD Workflow

BitChat uses GitHub Actions for automated quality assurance. The workflow is defined in .github/workflows/swift-tests.yml and triggers on every push or pull request to the main branch [.github/workflows/swift-tests.yml:3-8].

Build and Test Pipeline

Title: CI/CD Pipeline Flow

The pipeline runs tests in parallel across the app and local packages (BitLogger, BitFoundation) [.github/workflows/swift-tests.yml:22-30]. It utilizes actions/cache for build artifacts based on Package.resolved and source file hashes [.github/workflows/swift-tests.yml:43-51].

Performance Gating: Benchmarks are run serially to ensure stable numbers [.github/workflows/swift-tests.yml:99-104]. The check-perf-floors.sh script compares results against perf-floors.json to catch algorithmic regressions (e.g., O(n) to O(n²)) [scripts/check-perf-floors.sh:3-20]. A watchdog mechanism kills hung tests after 5 minutes to prevent runner starvation [.github/workflows/swift-tests.yml:68-95].

Sources: [.github/workflows/swift-tests.yml:1-133], [scripts/check-perf-floors.sh:1-182], [Package.swift:47-68]

---

Testing Strategies

Protocol and Cryptography Validation

The test suite ensures that cryptographic handshakes and binary packet structures are correctly handled.

• Noise Session Establishment: Tests verify the handshake sequence between peers using NoiseSessionManager to establish encrypted channels [bitchatTests/EndToEnd/PrivateChatE2ETests.swift:112-127].
• Packet Serialization: TestHelpers provides utilities to generate valid BitchatPacket and BitchatMessage instances for protocol validation [bitchatTests/TestUtilities/TestHelpers.swift:18-57].

Mesh and Integration Testing

The integration suite uses MockBLEService and TestNetworkHelper to simulate complex mesh topologies:

• Dynamic Topology: Tests simulate nodes moving out of range or switching neighbors mid-conversation to verify route persistence [bitchatTests/Integration/IntegrationTests.swift:56-83].
• Multi-Hop Relay: Validates that public messages propagate through a chain with proper ttl (Time To Live) decrementing [bitchatTests/EndToEnd/PublicChatE2ETests.swift:137-158].
• Network Partitions: Simulates two isolated groups of nodes and verifies they can communicate only after a "bridge" node connects them [bitchatTests/Integration/IntegrationTests.swift:85-122].

Code-to-System Relationship: Testing Infrastructure

Title: Testing Infrastructure Mapping

Protocol Flow Validation

Title: Mock Mesh Interaction Sequence

Sources: [bitchatTests/Mocks/MockBLEService.swift:29-205], [bitchatTests/Integration/IntegrationTests.swift:15-54], [bitchatTests/EndToEnd/PublicChatE2ETests.swift:82-158], [bitchatTests/TestUtilities/TestHelpers.swift:14-133], [bitchatTests/BLEServiceTests.swift:65-120]