|
| 1 | +--- |
| 2 | +id: flutter-integration-testing-ios |
| 3 | +title: Flutter iOS |
| 4 | +sidebar_label: Flutter iOS |
| 5 | +description: Run your Flutter integration tests for iOS |
| 6 | +--- |
| 7 | + |
| 8 | +import useBaseUrl from '@docusaurus/useBaseUrl'; |
| 9 | +import Tabs from '@theme/Tabs'; |
| 10 | +import TabItem from '@theme/TabItem'; |
| 11 | + |
| 12 | +Flutter compiles iOS [integration tests](https://docs.flutter.dev/cookbook/testing/integration/introduction) into [XCTests](https://developer.apple.com/documentation/xctest) so that they can be executed on Apple devices. The following will explain how to run your XCTests on Sauce Labs infrastructure. |
| 13 | + |
| 14 | +**To run an XCTest (or 'Flutter test') on Sauce Labs, you need to provide two test artifacts:** |
| 15 | +1. Your flutter-iOS app compiled as an `.app` or `.ipa` file. |
| 16 | +2. The `.xctestrun` file for that app. The [.xctestrun file](https://keith.github.io/xcode-man-pages/xcodebuild.xctestrun.5.html) is the config for your test, this is the same config that Xcode uses when it runs your tests on your development machine. |
| 17 | + |
| 18 | + |
| 19 | +## Contents |
| 20 | +1. [How to build the '.app' and '.xctestrun' files for your Flutter app.](#1-how-to-build-the-app-and-xctestrun-files-for-your-flutter-app) |
| 21 | +2. [How to run the flutter-iOS integration test on Sauce Labs infrastructure.](#2-how-to-run-flutter-ios-integration-tests-on-sauce-labs-infrastructure) |
| 22 | +3. [Sample Implementation](#example-implementation) |
| 23 | + |
| 24 | + |
| 25 | +:::info What You'll Need |
| 26 | + |
| 27 | +- A Sauce Labs account ([Log in](https://accounts.saucelabs.com/am/XUI/#login/) or sign up for |
| 28 | + a [free trial license](https://saucelabs.com/sign-up)) |
| 29 | +- Your Sauce Labs [Username and Access Key](https://app.saucelabs.com/user-settings) |
| 30 | +- Access to Sauce Labs Real Devices. Sauce Labs only supports XCTests on Real Devices, not virtual. |
| 31 | +- Flutter mobile app. If you don't have one, you could use our Flutter Demo App: |
| 32 | + - [Sauce Labs Flutter Demo App](https://github.com/saucelabs/my-demo-app-flutter) |
| 33 | +- `xcodebuild` tools |
| 34 | +- `zip` and/or `saucectl` |
| 35 | +::: |
| 36 | + |
| 37 | + |
| 38 | +## 1. How to build the '.app' and '.xctestrun' files for your Flutter app. |
| 39 | + |
| 40 | +:::note You need to setup your Flutter app for integration tests. |
| 41 | + |
| 42 | +Before you build your app, you must ensure that you correctly set up the `integration_tests` for your flutter-ios app. You can follow the [flutter documentation](https://github.com/flutter/flutter/tree/main/packages/integration_test#integration_test) to do so. The most relevant section is the part on [iOS Device Testing](https://github.com/flutter/flutter/tree/main/packages/integration_test#ios-device-testing). You can stop following Flutter's guide after you have executed the `xcodebuild build-for-testing` command. This command will generate the `.app` and `.xctestrun` files. |
| 43 | +::: |
| 44 | + |
| 45 | +To execute your xctest, we require your app (which must be packaged together with your XCTests) in '.app' or '.ipa' format. Additionally we need your your `.xctestrun` file, which is the config for your test. |
| 46 | + |
| 47 | +By default, Xcode will not persist the `.xctestrun` file if you kick off an XCTest on your development machine. To persist the `.xctestrun` file we need to use the `xcodebuild build-for-testing` command. Make sure you are using the correct `scheme` so it includes your integration tests. |
| 48 | + |
| 49 | +```shell |
| 50 | +# Example of the xcodebuild command to build the application. |
| 51 | +# You will need to adjust the args according to your app. |
| 52 | +output="../build/ios_integ" |
| 53 | +xcodebuild build-for-testing \ |
| 54 | + -workspace Runner.xcworkspace \ |
| 55 | + -scheme Runner \ |
| 56 | + -xcconfig Flutter/Release.xcconfig \ |
| 57 | + -configuration Release \ |
| 58 | + -derivedDataPath \ |
| 59 | + $output -sdk iphoneos |
| 60 | + |
| 61 | +# The .app and .xctestrun files will now be present in your output directory. In this case: `build/ios_integ/Products/Release-iphoneos` |
| 62 | +``` |
| 63 | + |
| 64 | + |
| 65 | +## 2. How to run flutter-iOS integration tests on Sauce Labs infrastructure |
| 66 | + |
| 67 | +To run your Flutter XCTest on Sauce Labs, you have two options: use `saucectl` or integrate with our APIs yourself. If you are unfamiliar with our APIs, we recommend using `saucectl` for ease of use and getting you started quickly. |
| 68 | + |
| 69 | + |
| 70 | +### Run XCTests via saucectl |
| 71 | + |
| 72 | +First install [saucectl](/docs/dev/cli/saucectl.md#installing-saucectl). **Note: minimum version is `0.192.0`.** Then you can use `saucectl` command to configure and run your test on Sauce Labs infrastructure. |
| 73 | + |
| 74 | +```shell |
| 75 | +# If it's the first time you're using saucectl, run: |
| 76 | +saucectl configure |
| 77 | + |
| 78 | +# follow the steps to configure your XCTest, with your `.app`/`.ipa` file and the `.xctestrun` test config. Use `Real Device` not `Virtual Device` |
| 79 | +saucectl init xctest |
| 80 | + |
| 81 | +# run the newly created XCTest config. |
| 82 | +saucectl run |
| 83 | +``` |
| 84 | + |
| 85 | +For further configuration options and info on how to use `saucectl` visit [/docs/mobile-apps/automated-testing/espresso-xcuitest/xcuitest.md](/docs/mobile-apps/automated-testing/espresso-xcuitest/xcuitest.md) |
| 86 | + |
| 87 | +### Run XCTests without saucectl |
| 88 | + |
| 89 | +If you prefer not to use saucectl, you can directly integrate with our APIs. |
| 90 | + |
| 91 | +**First**, compile your `.app` as an `.ipa` file as described [above](/docs/mobile-apps/automated-testing/ipa-files.md#building-an-ipa-from-an-app-bundle). |
| 92 | + |
| 93 | +**Second**, upload your `.ipa` and `.xctestrun` files to our AppStorage backend, see [AppStorage APIs](/docs/mobile-apps/app-storage.md#upload-apps-via-rest-api). |
| 94 | + |
| 95 | +**Third**, call our native testing API with the AppStorage IDs of the two files you just uploaded. See [RDC native /test API](/docs/dev/api/rdc.md#start-a-xctest-xcuitest-or-espresso-job). |
| 96 | + |
| 97 | +**Fourth**, poll the state of the job and wait until the `status` is `passed|failed|error|complete`. You can do this through the [Jobs API](/docs/dev/api/rdc.md#get-a-specific-real-device-job). |
| 98 | + |
| 99 | + |
| 100 | +## Example Implementation |
| 101 | + |
| 102 | +For a practical example of how to set up and run integration tests for Flutter apps, you can refer to |
| 103 | +the [Sauce Labs Flutter demo application](https://github.com/saucelabs/my-demo-app-flutter) repository. |
| 104 | +The steps outlined in this guide have already been implemented in that repository. You can follow along with the demo app to see how |
| 105 | +everything is configured and run your tests accordingly. |
0 commit comments