# Add Integration Tests to a Flutter App

Yes. An agent adds integration_test, writes end-to-end tests that drive your real routes and saved settings, runs them on web, and opens a PR with a CI job.

[Run this on Rush](https://cloud.getrush.ai/run/add-integration-tests/flutter/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with what the app has and lacks. In an app shaped like gskinnerTeam/flutter-wonderous-app, pubspec.yaml pins the Dart SDK at ^3.11.5 and Flutter at ^3.41.9, depends on go_router 17, get_it 7, provider, shared_preferences, flutter_localizations and intl, and lists only icons_launcher, flutter_lints 6 and dependency_validator under dev_dependencies. There is no flutter_test, no integration_test, no test/ directory and no integration_test/ directory. The workflows under .github/workflows build the web app with subosito/flutter-action on 3.41.9 and `flutter build web --wasm`, and two deploy workflows upload it; nothing runs `flutter analyze` or a test. The project has android, ios, macos, web and windows runners but no linux directory, which decides where the tests can run in a Linux sandbox.

Next it reads the flow a test must survive. lib/main.dart calls `registerSingletons()`, runs `WondersApp` on `MaterialApp.router` with the global `appRouter`, then awaits `appLogic.bootstrap()`, which loads settings, locale, wonders, timeline and collectibles, flips `isBootstrapComplete`, and sends the router to `/welcome` when `hasCompletedOnboarding` is false or to `/home` otherwise. lib/router.dart's `_handleRedirect` pins every path to `/` until bootstrap completes. Settings persist through `JsonPrefsFile`, which stores one JSON string under the key `settings.dat` in shared_preferences, so a test can set `hasCompletedOnboarding` before the app starts with `SharedPreferences.setMockInitialValues`. The intro screen builds three `_PageData` pages from the localized `introTitleJourney`, `introTitleExplore` and `introTitleDiscover` strings and goes home from the last page in `_handleIntroCompletePressed`, setting the flag as it leaves.

The tests it writes live in integration_test/app_test.dart under `IntegrationTestWidgetsFlutterBinding`. The first seeds empty preferences, starts the app and asserts the intro's first title, pages through all three with the localized strings as finders, taps the final button, and asserts the home screen is shown and the stored `settings.dat` now has `hasCompletedOnboarding` true. The second seeds the flag as already true, starts the app and asserts it lands on home without the intro, then opens a wonder's details through the `ScreenPaths.wonderDetails` route that resolves to `/home/wonder/<type>?t=0`, asserts the details tab renders, and navigates back. Each test calls `registerSingletons()` and `runApp` itself rather than `main()`, because `main()` preserves the native splash and the test binding must own the first frame. Finders use the app's localized strings from `AppLocalizations` rather than hard-coded English, since the locale comes from settings.

Then it runs them. With no linux runner directory, the sandbox target is the web build the repository already ships: the agent adds test_driver/integration_test.dart, starts chromedriver, and runs `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d web-server`, keeping the output. It adds flutter_test and integration_test from the SDK to dev_dependencies, runs `flutter pub get` and `flutter analyze` with the repository's flutter_lints 6 rules and 120-column formatter width, and runs `dart run dependency_validator`, which the project already depends on, so the new packages are declared and used. A new .github/workflows/integration_test.yml uses the same subosito action and 3.41.9 pin as build_web.yml, installs Chrome, and runs the same drive command on pull requests.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add integration tests to this Flutter app. Read pubspec.yaml, analysis_options.yaml, lib/main.dart, lib/router.dart, lib/logic/app_logic.dart, lib/logic/settings_logic.dart, lib/logic/common/json_prefs_file.dart, lib/ui/screens/intro/intro_screen.dart, the l10n files, and every workflow under .github/workflows first, and note which platform runner directories exist, how settings are persisted, and what the router does before and after bootstrap. Add flutter_test and integration_test as SDK dev dependencies and write integration_test/app_test.dart with at least two tests: a first launch that walks the onboarding and lands on home, asserting the persisted onboarding flag, and a returning launch seeded through SharedPreferences.setMockInitialValues that skips onboarding, opens one wonder's details route and returns. Start the app from the test with registerSingletons and runApp, not main. Use localized strings for finders. Add test_driver/integration_test.dart and run the tests in the sandbox on the web target with chromedriver, keeping the output. Run flutter analyze and dependency_validator. Add a workflow that runs the same drive command on pull requests with the Flutter version the existing web build pins. Open a pull request that lists each test, what it asserts, and the drive and analyze output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds integration_test/app_test.dart and test_driver/integration_test.dart, adds two SDK packages to dev_dependencies in pubspec.yaml with the matching pubspec.lock update, and adds .github/workflows/integration_test.yml. No file under lib changes; if a widget needs a key to be found reliably, the description says which one and why.

The description names each test and its assertions in a short table, then quotes the `flutter drive` run on the web target from the sandbox, the `flutter analyze` result under flutter_lints 6, and the dependency_validator output showing the new packages as declared and used. It states that the tests ran on web because the repository has no Linux runner, and which device the workflow uses.

Before merging, a reviewer runs the same command on a phone or simulator to confirm the finders hold on a touch layout, checks that the seeded preferences match the JSON shape `SettingsLogic` reads, and decides whether the workflow should also build the Android or iOS target. A third test for the timeline or the collection screen is a follow-up on the same session.

## Run it on every nightly

Add an automation to the Project with this prompt and a schedule trigger, `every` set to `1d`. Each night the agent reads the current routes and screens, and when the app has no integration test for a screen that is reachable from the router, it writes one and opens a pull request by morning; when every reachable screen is covered, it changes nothing and the run's result says so.

A team with several Flutter apps adds the same automation to each Project, one run per app per night. Each run reads its own pubspec, router and runner directories, so an app that already has a linux directory runs its tests on the desktop target while this one runs on web, and each run opens its own pull request.

## Why run it on Rush?

Integration tests on a Flutter app are only trustworthy after they have run on a real target with the real bootstrap, including the redirect that pins every route to the splash until settings load. That needs a Flutter SDK at the pinned version, a browser and a driver, and a few iterations on finders. The agent does all of it in its own sandbox and the pull request carries the drive output, so the first review is of tests that have passed rather than tests that might.

The record also answers the question reviewers ask first: why these tests. The transcript shows the agent reading the router, the onboarding flag and the preferences file, and choosing to seed `settings.dat` rather than tap through onboarding twice. A reviewer who wants the collection screen covered next asks in a follow-up, and the parked sandbox still has the SDK, the build and Chrome ready.

## Frequently asked questions

### Why do the tests run on web rather than a desktop target?

Because the repository has android, ios, macos, web and windows directories but no linux one, so a Linux sandbox cannot build a desktop binary. The web target is what the existing build workflow already produces, and flutter drive with chromedriver runs integration tests against it.

### Why not start the app with main()?

main() preserves the native splash screen until bootstrap completes and the integration test binding needs to own the first frame. The test calls registerSingletons and runApp, then awaits appLogic.bootstrap itself, which is the same sequence main runs without the splash call.

### How does a test skip onboarding?

SettingsLogic persists its values as one JSON string under the key settings.dat in shared_preferences. The test seeds that key with hasCompletedOnboarding true through SharedPreferences.setMockInitialValues before the app starts, so bootstrap routes straight to home.

### Will the finders break when the copy changes?

The tests find text through the generated AppLocalizations strings rather than literal English, so a wording change in the ARB files flows into the test. A redesign that removes a page would fail the test, which is the point.

### Does this change the existing build and deploy workflows?

No. The new workflow is a separate file that runs on pull requests, with the same Flutter version pin the web build uses. The build and deploy workflows keep their workflow_dispatch triggers.

## More Flutter jobs

- [Add Local Notifications to a Flutter App](https://getrush.ai/run/add-local-notifications/flutter/)
- [Add a Native Splash Screen to a Flutter App](https://getrush.ai/run/add-splash-screen/flutter/)
- [Replace Deprecated Flutter APIs Across an App and Make the Analyzer Catch the Next Ones](https://getrush.ai/run/fix-deprecated-apis/flutter/)

## More jobs like this: Write the missing tests

- [Add a Locust Load Test to CI](https://getrush.ai/run/add-load-test-to-ci/locust/)
- [Add a Migration Check to CI for a TypeORM Project](https://getrush.ai/run/add-migration-check-to-ci/typeorm/)
- [Write Migration Rollback Tests for Alembic](https://getrush.ai/run/add-migration-rollback-tests/alembic/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
