JamReady
JamReady is a Flutter app for managing a Roller Derby jam timer. It supports both standalone (offline) mode and remote mode, where it connects to a CRG Derby Scoreboard instance over WebSocket and acts as a remote control.
Prerequisites
- Flutter SDK 3.41.6 (the version pinned in CI)
- Dart SDK (comes with Flutter)
- Xcode (for iOS/macOS) and/or Android Studio (for Android)
Verify your environment:
flutter doctor
Setup
flutter pub get --enforce-lockfile
Running
List connected devices:
flutter devices
Run on a device:
flutter run -d <device-id>
Testing
make unit # unit and widget tests (no device required)
make integration # offline integration test (requires a connected device or emulator)
make test # both of the above
Scoreboard Integration Tests
The scoreboard tests connect to a real CRG scoreboard over WebSocket and verify compatibility across multiple versions. They require Docker and git (the scoreboard build runs entirely inside Docker — no local JDK or Ant needed).
Build the scoreboard images once before running either suite. You can build every supported version or select specific versions:
make build-scoreboards
./scripts/build-scoreboard-images.sh --versions v2025.9,v2025.8
The source for each scoreboard version is cloned and compiled inside a multi-stage Docker build (scripts/scoreboard.Dockerfile).
Combined compatibility run
Run both suites and create one version-first Allure report:
./scripts/test-scoreboards.sh --jobs 4 --emulator-jobs 2
--jobs controls headless remote-engine workers. --emulator-jobs is independently capped at the number of running Android emulators, so it cannot overcommit devices. The coordinator runs the headless suite first, then the emulator suite, and writes one report to test-results/scoreboards-<timestamp>-<pid>/allure-report/index.html.
Headless remote-engine suite
The fast suite exercises RemoteGameEngine and ScoreboardState directly, without building the app or launching an emulator. Local runs can fan out versions across independent Flutter workers; each worker uses an isolated copy of the current checkout, so uncommitted changes are included and concurrent Flutter builds do not share build/ or .dart_tool/.
./scripts/test-remote-engine-scoreboards.sh
./scripts/test-remote-engine-scoreboards.sh --versions v2025.9,v2025.8
./scripts/test-remote-engine-scoreboards.sh --jobs 2
Useful options:
--versions Comma-separated list of versions to test
--host Host address the tests connect to (default: 127.0.0.1)
--port First Docker host port to try (default: 8001)
--jobs Versions to run concurrently locally (default: 1)
--results-dir Parent directory for local reports (default: test-results)
--no-html Leave raw Allure result files without generating HTML
The runner finds an available Docker port for each worker, including a retry if Docker loses a port-binding race. A local run writes logs and raw Allure results to test-results/remote-engine-<timestamp>-<pid>/, plus a self-contained report at allure-report/index.html that can be opened directly from Finder. Report generation uses npx -y allure@3, so it requires Node.js 20+; use --no-html to skip it.
Arguments after -- are passed to flutter test. GitHub Actions continues to emit its existing per-version JSON files for the GitHub test reporter.
App integration suite
The UI-driven suite builds and controls the Flutter app on Android emulators. When several emulators are already running, it fans versions out across them; each concurrent worker uses an isolated copy of the current checkout, an independent Docker port, and a distinct Docker container. If no emulator is running, the script starts one and runs sequentially.
make test-scoreboards
./scripts/test-all-scoreboards.sh --versions v2025.9,v2025.8
./scripts/test-all-scoreboards.sh --jobs 2
Useful options:
--versions Comma-separated list of versions to test
--avd AVD name (default: first from `emulator -list-avds`)
--host Host address the tests connect to (default: 10.0.2.2)
--port First Docker host port to try (default: 8001)
--jobs Maximum emulator workers to use (default: all running emulators)
--results-dir Parent directory for local reports (default: test-results)
--no-html Leave raw Allure result files without generating HTML
--jobs is capped at the number of available emulators (and test versions), so asking for more never starts extra emulators. The runner selects an available Docker port for each worker and retries after a binding race. It writes logs and raw Allure results to test-results/scoreboard-integration-<timestamp>-<pid>/, plus a self-contained report at allure-report/index.html when Node.js 20+ is available.
Arguments after -- are passed to flutter test.
Continuous integration
The main CI workflow runs static analysis and unit/widget tests on pushes and pull requests to main. Test results are uploaded as JSON artifacts and published as a GitHub Check. Pull requests also run the headless remote-engine suite as a matrix across the supported CRG scoreboard versions, with a separate artifact and check for each version.
Releasing
The release script handles versioning, changelog generation, and tagging. It requires the claude CLI to generate the changelog.
./scripts/release.sh
It will ask whether this is a stable or pre-release, which version component to bump, and (for pre-releases) a suffix like rc1 or beta1. It then generates a changelog from commits since the last release using Claude, shows it for confirmation, commits the version bump to pubspec.yaml, creates an annotated git tag, and offers to push. Pushing the tag triggers the GitHub Actions release workflow, which publishes a GitHub release with the changelog as the release notes.
Store builds (manual)
The GitHub release contains release notes only — store builds must be created and uploaded manually using make release, which runs all tests (including scoreboard compatibility tests) and then builds both artifacts:
make release
This requires:
Once built, upload the artifacts via their respective consoles:
- Android:
build/app/outputs/bundle/release/app-release.aab → Play Console
- iOS:
build/ios/ipa/*.ipa → Xcode Organizer or xcrun altool
Static Analysis
flutter analyze
Project Structure
lib/ app source (screens, widgets, models, services)
test/ unit and widget tests
integration_test/ integration tests (run separately)
remote_engine_test/ headless CRG scoreboard compatibility tests
assets/ app assets
scripts/ build and test utilities
