Skip to content
Antimatter

Testing Guide

This guide covers the testing strategies across the Antimatter monorepo — Gateway, adapters, and mobile apps.

Philosophy

Section titled “Philosophy”

Antimatter follows a pragmatic testing pyramid:

  • Unit tests for business logic — protocol parsing, message routing, crypto verification.
  • Integration tests for WebSocket protocol flows — auth handshake, message forwarding.
  • End-to-end tests for critical paths — QR pairing, agent prompt round-trip.

Gateway Tests (core/)

Section titled “Gateway Tests (core/)”
Terminal window
cd core/
uv run pytest                         # All tests
uv run pytest tests/unit/             # Unit tests only
uv run pytest tests/integration/      # Integration tests
uv run pytest -v --tb=short           # Verbose output
uv run pytest --cov=antimatter_core   # With coverage

Key Test Areas

Section titled “Key Test Areas”
Module Tests
auth.py Token verification, Ed25519 handshake, timing-safe compare
router.py Message routing to correct adapter, unknown type handling
tunnel.py Cloudflare tunnel lifecycle, reconnect logic

Android Tests (android/)

Section titled “Android Tests (android/)”
Terminal window
cd android/


# Unit tests (JVM, no device needed)
./gradlew testDebugUnitTest


# Instrumented tests (requires connected device/emulator)
./gradlew connectedDebugAndroidTest


# Single module tests
./gradlew :core:network:testDebugUnitTest




# Coverage report
./gradlew testDebugUnitTest jacocoTestReport

Key Test Areas

Section titled “Key Test Areas”
Module Tests
:core:network BridgeWebSocket auth flow, message deserialization
:core:data Room DAO queries, FTS search
:feature:chat ChatViewModel state transitions, step rendering

| :feature:connect | QR parsing, connection state machine |

iOS Tests (ios/)

Section titled “iOS Tests (ios/)”

Open the project in Xcode and use ⌘U to run all tests, or via CLI:

Terminal window
xcodebuild test \
  -workspace ios/AntimatterApp.xcworkspace \
  -scheme AntimatterApp \
  -destination 'platform=iOS Simulator,name=iPhone 16'

Key Test Areas

Section titled “Key Test Areas”
Module Tests
Crypto Ed25519 verification, AES-GCM decrypt
WebSocket Auth challenge flow, message deserialization

Adapter Tests

Section titled “Adapter Tests”

AG Adapter (TypeScript)

Section titled “AG Adapter (TypeScript)”
Terminal window
cd adapters/ag/
npm test               # Jest unit tests
npm run lint           # Type-check only

AG2 Adapter (Python)

Section titled “AG2 Adapter (Python)”
Terminal window
cd adapters/ag2/
uv run pytest

CC Adapter (Node.js)

Section titled “CC Adapter (Node.js)”
Terminal window
cd adapters/cc/
npm test

Manual Testing Checklist

Section titled “Manual Testing Checklist”

Before submitting a PR that touches the auth flow or protocol, verify these scenarios manually:

  • Fresh QR pairing completes successfully
  • Re-pairing (scan new QR) correctly replaces the old session
  • Invalid token produces close code 4001
  • App reconnects cleanly after Gateway restart
  • PTY terminal: start session, type commands, resize, close
  • File browser loads workspace tree
  • Prompt injection reaches active agent
  • Push notification fires on agent task completion
  • Biometric gate blocks connection until authenticated
Saif Mukhtar

Saif Mukhtar

Creator & Lead Developer of Antimatter · Android, iOS & Python engineer

🌐 saifmukhtar.dev⭐ GitHub👤 Gravatar❤️ Sponsor