# Running unit and UI tests on Flutter apps

The **Flutter Test** Step allows you to run unit tests, widget tests, and integration (also referred to as end-to-end or UI testing) tests on your Flutter app on Bitrise. The Step runs the `flutter test` command and saves the `json` file that is generated by the command. You can then view the test results at any time: [Viewing test results](/bitrise-ci/testing/test-reports/viewing-test-results).

:::tip[Code coverage]

The **Flutter Test** Step can also generate code coverage reports.

:::

:::tip[UI testing with Maestro]

To test your Flutter app's UI from the outside, with flows that tap and type on an emulator or simulator, check out Maestro: [Running Maestro tests on Bitrise](/bitrise-ci/testing/running-maestro-tests-on-bitrise).

:::

To run tests using **Flutter Test**:

**Workflow Editor**

1. Include tests in your Flutter project.

   For more information on how to write tests and include them in your Flutter project, check the official Flutter documentation: [Testing Flutter apps](https://docs.flutter.dev/testing).
1. Add the **Flutter Install** Step to your Workflow.

   This Step runs the initial setup of the Flutter SDK and installs any missing components.
1. Make sure that the **Flutter Install** Step installs the correct version of the Flutter SDK for your app: check the **Flutter SDK version or bundle URL** input.

   ![flutter-install-step.png](/img/2026-07-16-flutter-install-step.png)

   The input's default value is **stable**, which installs the latest stable version of the SDK. You can, however, set the value to a specific version tag, a branch label, or a Flutter SDK bundle URL:

   - You can find the available version tags here: [Version tags](https://github.com/flutter/flutter/tags).
   - You can find the available branch labels here: [Branch labels](https://github.com/flutter/flutter/branches).

   :::tip[Installation bundle URL]

   You can also install the Flutter SDK from an installation bundle URL: set the URL as the value of the same **Flutter SDK version or bundle URL** input, for example `https://storage.googleapis.com/flutter_infra/releases/beta/macos/flutter_macos_v1.6.3-beta.zip`.

   :::
1. Add the **Flutter Test** Step to your Workflow. It should be after the **Flutter Install** Step.

   The Step runs the `flutter test` command with optional flags. It can also check code coverage.
1. Make sure the **Project Location** input points to the root directory of your Flutter project.

   ![flutter-test-step.png](/img/2026-07-16-flutter-test-step.png)

   - If the project scanner automatically detected it as a Flutter project when [adding it as an app](/bitrise-ci/getting-started/adding-a-new-project) on Bitrise, you don't have to change the default value.
   - If you configured the app manually, check that the location is correct. You can do so by going to the **Env Vars** tab on the Workflow Editor, and checking the BITRISE_FLUTTER_PROJECT_LOCATION [Environment Variable](/bitrise-ci/configure-builds/environment-variables).
1. By default, the Step will find and run all tests. But you can configure it to run only selected tests: use the **Test files pattern** input to tell the Step which tests to run.

   The input accepts both * and ** glob formats. For example, `lib/**/*_test.dart` is a valid input.

   ![flutter-test-files-pattern.png](/img/2026-07-16-flutter-test-files-pattern.png)
1. Optionally, use the **Additional parameters** input to append flags to the `flutter test` command.

   To see the available options, run the `flutter help test` command. You can do so on your own device or in a **Script** Step on Bitrise.
1. Optionally, set the **Generate code coverage files?** input to **yes** to generate code coverage files.

   With this input turned on, the `--coverage` flag is appended to the `flutter test` command.
1. Optionally, you can access the generated json test report and the code coverage file (`lcov.info`) in subsequent Steps by using the BITRISE_FLUTTER_TESTRESULT_PATH and the BITRISE_FLUTTER_COVERAGE_PATH [Environment Variables](/bitrise-ci/configure-builds/environment-variables#setting-and-managing-env-vars-during-a-build).
1. Add the **Deploy to Bitrise.io** Step to your Workflow to view test results: [Deploying test results](/bitrise-ci/testing/test-reports/deploying-test-results).

**Configuration YAML**

1. Include tests in your Flutter project.

   For more information on how to write tests and include them in your Flutter project, check the official Flutter documentation: [Testing Flutter apps](https://docs.flutter.dev/testing).
1. Add the `flutter-installer` Step to your Workflow.

   This Step runs the initial setup of the Flutter SDK and installs any missing components.

   ```yaml
   primary:
     description: |
       Builds project and runs tests.
     steps:
       - activate-ssh-key: {}
       - git-clone: {}
       - flutter-installer:
           inputs:
   ```
1. Make sure that the Step installs the correct version of the Flutter SDK for your app: you can specify the version using the `version` input.

   The input's default value is `stable`, which installs the latest stable version of the SDK. If you do not see the `version` input in your Configuration YAML file, it is set to the default value. You can, however, set the value to a specific version tag, a branch label, or a Flutter SDK bundle URL:

   - You can find the available version tags here: [Version tags](https://github.com/flutter/flutter/tags).
   - You can find the available branch labels here: [Branch labels](https://github.com/flutter/flutter/branches).

   ```yaml
   # Installing version 3.7.7 of the Flutter SDK
   - flutter-installer:
       inputs:
       - version: 3.7.7
   ```

   :::tip[Installation bundle URL]

   You can also install the Flutter SDK from an installation bundle URL: set the URL as the value of the same `version` input. The URL is expected to begin with `https://storage.googleapis.com/flutter_infra`. For example:

   ```yaml
   - flutter-installer:
       inputs:
       - version: https://storage.googleapis.com/flutter_infra/releases/beta/macos/flutter_macos_v1.6.3-beta.zip
   ```

   :::
1. Add the `flutter-test` Step to your Workflow. It should be after the `flutter-installer` Step.

   The Step runs the `flutter test` command with optional flags. It can also check code coverage.

   ```yaml
   primary:
     description: |
       Builds project and runs tests.
     steps:
       - activate-ssh-key: {}
       - git-clone: {}
       - flutter-installer:
           inputs:
           - version: stable
       - restore-dart-cache: {}
       - flutter-test:
           inputs:
   ```
1. Make sure the `project_location` input points to the root directory of your Flutter project.

   ```yaml
   - flutter-test:
       inputs:
       - project_location: "$BITRISE_FLUTTER_PROJECT_LOCATION"
   ```

   - If the project scanner automatically detected it as a Flutter project when [adding it as an app](/bitrise-ci/getting-started/adding-a-new-project) on Bitrise, you don't have to change the default value, which is BITRISE_FLUTTER_PROJECT_LOCATION.
   - If you configured the app manually, check that the location is correct. You can check where BITRISE_FLUTTER_PROJECT_LOCATION points in the `envs` property of the `app`:

     ```yaml
     # Pointing to the root directory
     app:
       envs:
         - opts:
             is_expand: false
           BITRISE_FLUTTER_PROJECT_LOCATION: .
     ```
1. By default, the Step will find and run all tests. But you can configure it to run only selected tests: use the `tests_path_pattern` input to tell the Step which tests to run.

   The input accepts both * and ** glob formats. For example, `lib/**/*_test.dart` is a valid input.

   ```yaml
   - flutter-test:
       inputs:
       - tests_path_pattern: /lib/*_test.dart
   ```
1. Optionally, use the `additional_params` input to append flags to the `flutter test` command.

   To see the available options, run the `flutter help test` command. You can do so on your own device or in a **Script** Step on Bitrise.

   ```yaml
   - flutter-test:
       inputs:
   # setting a test timeout of 60 seconds
       - additional_params: --timeout 60s
   ```
1. Optionally, set the `generate_code_coverage_files` input to `'yes'` to generate code coverage files.

   With this input turned on, the `--coverage` flag is appended to the `flutter test` command.

   ```yaml
   - flutter-test:
       inputs:
       - generate_code_coverage_files: 'yes'
   ```
1. Optionally, you can access the generated json test report and the code coverage file (`lcov.info`) in subsequent Steps by using the BITRISE_FLUTTER_TESTRESULT_PATH and the BITRISE_FLUTTER_COVERAGE_PATH [Environment Variables](/bitrise-ci/configure-builds/environment-variables#setting-and-managing-env-vars-during-a-build).
1. Add the `deploy-to-bitrise-io` Step to view test results: [Deploying test results](/bitrise-ci/testing/test-reports/deploying-test-results).

   ```yaml
   primary:
     description: |
       Builds project and runs tests.
     steps:
       - activate-ssh-key: {}
       - git-clone: {}
       - flutter-installer:
           inputs:
           - version: stable
       - restore-dart-cache: {}
       - flutter-test:
           inputs:
           - project_location: "$BITRISE_FLUTTER_PROJECT_LOCATION"
           - generate_code_coverage_files: 'yes'
           - tests_path_pattern: /lib/*_test.dart
      - save-dart-cache: {}    
      - deploy-to-bitrise-io: {}
   ```
