Dat Vu
124 lines
5.2 KiB
Markdown
124 lines
5.2 KiB
Markdown
# 80. Patrol Web Integration Test — Setup & Execution
|
|
|
|
Date: 2026-04-15
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Related ADRs
|
|
|
|
- [ADR-0053](./0053-patrol-integration-test.md) — Patrol for mobile integration testing (foundation)
|
|
- [ADR-0081](./0081-patrol-web-test-architecture.md) — Cross-platform test architecture
|
|
- [ADR-0082](./0082-patrol-web-test-migration-guide.md) — Migration guide & implementation example
|
|
- [ADR-0083](./0083-patrol-web-test-migration-plan.md) — PR-by-PR migration plan
|
|
|
|
## Context
|
|
|
|
[ADR-0053](./0053-patrol-integration-test.md) established Patrol for mobile (Android/iOS) integration testing. As Twake Mail is also deployed as a web app, the same level of E2E coverage is needed on the browser. Patrol 4.x added Chrome support via `--device=chrome`, making it feasible to extend the existing setup without introducing a second testing framework.
|
|
|
|
## Decision
|
|
|
|
Use Patrol with Chrome as the target device for web integration testing, sharing the same backend Docker infrastructure used for mobile tests.
|
|
|
|
### Prerequisites
|
|
|
|
- Flutter 3.38.9
|
|
- Patrol CLI 4.3.1: `dart pub global activate patrol_cli 4.3.1`
|
|
- `patrol` package **4.5.0** (and `patrol_finders 3.x`, `patrol_log 0.8.x`) — requires upgrading from the 3.x currently in `pubspec.yaml`
|
|
- Docker Desktop (running)
|
|
- `openssl` installed (used to generate JWT keys for the backend)
|
|
|
|
> Unlike mobile tests, web tests do **not** require `ngrok` or `jq`. The app runs at `localhost` and Chrome connects to it directly — no traffic forwarding needed.
|
|
|
|
### Environment Variables
|
|
|
|
All tests receive configuration via `--dart-define`. Store values in an env file and source it in the run scripts — this keeps credentials out of command-line history and git history (add the file to `.gitignore`):
|
|
|
|
```bash
|
|
# integration_test/test_config.env
|
|
BASIC_AUTH_URL=http://localhost/
|
|
USERNAME=test_user
|
|
PASSWORD=test_password
|
|
BASIC_AUTH_EMAIL=test@example.com
|
|
ADDITIONAL_MAIL_RECIPIENT=recipient@example.com
|
|
```
|
|
|
|
The run scripts source this file and forward each value:
|
|
|
|
```bash
|
|
source integration_test/test_config.env
|
|
patrol test \
|
|
--dart-define=BASIC_AUTH_URL=$BASIC_AUTH_URL \
|
|
--dart-define=USERNAME=$USERNAME \
|
|
--dart-define=PASSWORD=$PASSWORD \
|
|
--dart-define=BASIC_AUTH_EMAIL=$BASIC_AUTH_EMAIL \
|
|
--dart-define=ADDITIONAL_MAIL_RECIPIENT=$ADDITIONAL_MAIL_RECIPIENT \
|
|
...
|
|
```
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `BASIC_AUTH_URL` | App server URL (e.g. `http://localhost/`) |
|
|
| `USERNAME` | Test account username |
|
|
| `PASSWORD` | Test account password |
|
|
| `BASIC_AUTH_EMAIL` | Test account email address |
|
|
| `ADDITIONAL_MAIL_RECIPIENT` | Secondary email for multi-recipient tests |
|
|
|
|
> `--dart-define-from-file` only accepts JSON, not `.env` format, so sourcing in the script is the correct approach.
|
|
|
|
### Running Locally (with visible browser)
|
|
|
|
```bash
|
|
./scripts/patrol-web-local-integration-test-with-docker.sh
|
|
```
|
|
|
|
This starts the Docker backend, then runs patrol with Chrome visible. Useful during development.
|
|
|
|
To run a single test file, edit the script and replace `patrol test -v` with:
|
|
|
|
```bash
|
|
patrol test -v -t integration_test/tests/composer/send_email_test.dart
|
|
```
|
|
|
|
> After migrating to the architecture defined in [ADR-0081](./0081-patrol-web-test-architecture.md), test files no longer have a `web_` prefix — one file covers all platforms.
|
|
|
|
### Running in CI (headless)
|
|
|
|
```bash
|
|
./scripts/patrol-web-integration-test-with-docker.sh
|
|
```
|
|
|
|
Adds `--web-headless=true` — no display required. The GitHub Actions workflow (`.github/workflows/patrol-web-integration-test.yaml`) runs this script on pull requests.
|
|
|
|
### CI Orchestration — Running the Full Project
|
|
|
|
Mobile and web test suites run as **separate parallel jobs** in CI. Each job targets its own platform:
|
|
|
|
```text
|
|
PR opened / push
|
|
│
|
|
├── job: patrol-mobile-integration-test (ubuntu-latest + Android emulator)
|
|
│ patrol test --device=android
|
|
│
|
|
└── job: patrol-web-integration-test (ubuntu-latest + Chrome via Patrol)
|
|
./scripts/patrol-web-integration-test-with-docker.sh
|
|
# patrol test --device=chrome --web-headless=true
|
|
```
|
|
|
|
The two jobs are independent — they share no state and can run concurrently. A PR is gated on **both** jobs passing.
|
|
|
|
Platform filtering is handled automatically by `runPatrolTest()` (see [ADR-0082](./0082-patrol-web-test-migration-guide.md)). Tests that do not apply to the current platform skip themselves — no `--exclude-tags` flag needed in either job.
|
|
|
|
### Viewing Results
|
|
|
|
- **Terminal:** Patrol prints pass/fail per test with full stack traces on failure.
|
|
- **GitHub Actions:** Results appear in the workflow run summary under the "Test" step. Each platform job has its own step, making it easy to identify which platform a failure comes from.
|
|
|
|
## Consequences
|
|
|
|
- Web and mobile tests share the same test files; platform-only tests skip themselves in `runPatrolTest()` — no manual tagging required.
|
|
- The same Docker JMAP backend serves both platforms — no additional infrastructure needed.
|
|
- Data isolation limitations from [ADR-0053](./0053-patrol-integration-test.md) still apply: backend state is shared across all tests in a single run.
|
|
- Patrol automatically installs and manages Chromium — no manual Chrome installation is needed on local machines or CI runners.
|