From 3e51b1f10f20e7d01933c3384b932ab64d3248f0 Mon Sep 17 00:00:00 2001 From: Ryan Smith Date: Sat, 11 Jul 2026 11:16:50 -0700 Subject: [PATCH] Update README.md to reference new headless integratin tests --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index bed30b4..5a9bf32 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ JamReady is a Flutter app for managing a Roller Derby jam timer. It supports bot ## Prerequisites -- Flutter SDK (stable channel) +- 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) @@ -17,7 +17,7 @@ flutter doctor ## Setup ```bash -flutter pub get +flutter pub get --enforce-lockfile ``` ## Running @@ -44,28 +44,61 @@ make test # both of the above ## Scoreboard Integration Tests -The scoreboard integration tests connect to a live CRG scoreboard and verify compatibility across multiple versions. They require Docker and git (the build runs entirely inside Docker — no local JDK or Ant needed). +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: ```bash -make build-scoreboards # build a Docker image for each supported scoreboard version (run once) -make test-scoreboards # run the full suite against each image, newest version first +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`). The test suite requires a connected Android device or emulator, and stops on the first failure. +The source for each scoreboard version is cloned and compiled inside a multi-stage Docker build (`scripts/scoreboard.Dockerfile`). + +### Headless remote-engine suite -To pass options to the test runner (e.g. to test specific versions), call the script directly: +The fast suite exercises `RemoteGameEngine` and `ScoreboardState` directly, without building the app or launching an emulator. It runs against every scoreboard image, newest version first, stops on the first failure, and writes a Flutter JSON report for each version to `test-results/`. ```bash -./scripts/test-all-scoreboards.sh --versions v2025.9,v2025.8 +./scripts/test-remote-engine-scoreboards.sh +./scripts/test-remote-engine-scoreboards.sh --versions v2025.9,v2025.8 ``` +Useful options: + +``` +--versions Comma-separated list of versions to test +--host Host address the tests connect to (default: 127.0.0.1) +--port Docker host port (default: 8001) +--results-dir JSON report directory (default: test-results) ``` + +Arguments after `--` are passed to `flutter test`. + +### App integration suite + +The UI-driven suite builds and controls the Flutter app on an Android emulator. It also runs against each scoreboard image, newest version first, and stops on the first failure. + +```bash +make test-scoreboards +./scripts/test-all-scoreboards.sh --versions v2025.9,v2025.8 +``` + +Useful options: + +```text --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 Docker host port (default: 8001) ``` +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. The older `v2023.7` scoreboard is currently excluded from that CI matrix while its failing test is investigated. + ## Releasing The release script handles versioning, changelog generation, and tagging. It requires the [`claude` CLI](https://claude.ai/download) to generate the changelog. @@ -112,6 +145,7 @@ flutter analyze 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 ```