---
title: test
---

### Synopsis

Run integration tests.

```
patrol test
```

To see all available options and flags, run `patrol test --help`.

### Description

This command is the one use you'll be using most often.

`patrol test` does the following things:

1. Builds the app under test (AUT) and the instrumentation app
2. Installs the AUT and the instrumentation on the selected device
3. Runs the tests natively, and reports results back in native format.

Under the hood, it calls Gradle (when testing on Android) and `xcodebuild` (when
testing on iOS).

### Discussion

By default, `patrol test` runs all integration tests (files ending with
`_test.dart` located in the `patrol_test` directory). You can customize the test directory by setting `test_directory` in your `pubspec.yaml` under the `patrol` section.

To run a single test, use `--target`:

```
patrol test --target patrol_test/login_test.dart
```

You can use `--target` more than once to run multiple tests:

```
patrol test \
  --target patrol_test/login_test.dart \
  --target patrol_test/app_test.dart
```

Or alternatively:

```
patrol test --targets patrol_test/login_test.dart,patrol_test/app_test.dart
```

Test files must end with `_test.dart`. Otherwise the file is not considered a
test and is not run.

<Info>There's no difference between `--target` and `--targets`.</Info>

### Tags

You can use tags to run only tests with specific tags. 

First specify tags in your patrol tests:

```dart
  patrol(
    'example test with tag',
    tags: ['android'],
    ($) async {
      await createApp($);

      await $(FloatingActionButton).tap();
      expect($(#counterText).text, '1');
    },
  );

  patrol(
    'example test with two tags',
    tags: ['android', 'ios'],
    ($) async {
      await createApp($);

      await $(FloatingActionButton).tap();
      expect($(#counterText).text, '1');
    },
  );
```

Then you can run tests with the tags you specified:

```bash
patrol test --tags android
patrol test --tags=android
patrol test --tags='android||ios'
patrol test --tags='(android || ios)'
patrol test --tags='(android && tablet)'
```

You can also use `--exclude-tags` to exclude tests with specific tags:

```bash
patrol test --exclude-tags android
patrol test --exclude-tags='(android||ios)'
```

<Info>
    For comprehensive information about tag syntax, complex expressions, and advanced usage, see
    the [Patrol tags documentation](https://patrol.leancode.co/documentation/patrol-tags).
</Info>

### Coverage

<Warning>
        Coverage collection is currently not supported on macOS.
</Warning>

To collect coverage from patrol tests, use `--coverage`.

```
patrol test --coverage
```

The LCOV report will be saved to `/coverage/patrol_lcov.info`.

Additionally, you can exclude certain files from the report using glob patterns and `--coverage-ignore` option.
For instance,

```
patrol test --coverage --coverage-ignore="**/*.g.dart"
```

excludes all files ending with `.g.dart`.

### Build versioning

You can specify custom build number and build name using the `--build-name` and `--build-number` flags. These work
the same as in Flutter CLI:

- `--build-name`: Version name of the app. (e.g. `1.2.3`)
- `--build-number`: Version code of the app. (e.g. `123`)

```
patrol test --build-name=1.2.3 --build-number=123
patrol test --target patrol_test/login_test.dart --build-name=1.2.3 --build-number=123
```

### Isolation of test runs

To achieve full isolation between test runs:
- On Android: set `clearPackageData` to `true` in your `build.gradle` file,
- On iOS Simulator: use the `--full-isolation` flag

<Warning>
    This functionality is experimental on iOS and might be removed in the future releases.
</Warning>

```bash
patrol test --full-isolation
```

### Web Platform

Patrol supports running tests on Flutter web using Playwright. To run tests on web:

```bash
patrol test --device chrome
```

When running on web:
- Tests execute in Chromium browser via Playwright
- CLI arguments can be used to configure Playwright
- Test results are generated in `test-results/`

#### Arguments

Playwright configuration is updated with values passed to the command. This allows direct control over Playwright
features such as reporting. To see the full list of supported arguments, run `patrol test --help`.

**Note:** Some arguments are not supported on web:
- `--flavor`: Flavors are not supported for Flutter web
- `--uninstall`: Not applicable to web platform
- `--clear-permissions`: Not applicable to web platform
- `--full-isolation`: Not applicable to web platform

### Under the hood

`patrol test` basically calls `patrol build` and then runs the built app
binaries. For more info, read [docs of `patrol build`][patrol_build].

[patrol_build]: /cli-commands/build