Integrate your XCUITest test suite with App Percy

Create new app project on percy dashboard

Sign in to Percy and create a new app type project. After you’ve created the project, you’ll be shown a PERCY_TOKEN environment variable. Percy will use the PERCY_TOKEN to know which organisation and project to upload the screenshots to. You will need this PERCY_TOKEN in next steps.

Set the project token as an environment variable

To set the project token as an environment variable, include the PERCY_TOKEN in the curl command as shown in step 6.

Install Percy packages

Include the App Percy SDK dependency in the XCode package manager using the following command:

1. Launch XCode and select your test application.
2. Go to File > Add Packages.
3. On the Apple Swift Packages window, in the Search or Enter Package URL field, enter https://github.com/percy/percy-xcui-swift. You will see percy-xcui-swift package listed in the search results.
4. Click Add Package.

Install dependencies

1. Select your XCUI test project as the target project from the drop-down list on the Choose Package Products for percy-xcui-swift window.
2. Click Add Package and you will see percy-xcui-swift is added under the Package Dependencies in XCode editor.

Update test script

We are passing the required arguments.percy.screenshot method.

The screenshot method arguments are:

• name\ (required) - The screenshot name; must be unique to each screenshot
• Additional screenshot options (overrides any project options):
  • setFullScreen(Boolean) - Indicates whether the app is currently in fullscreen mode.
  • setStatusBarHeight(Int) - Specifies the height of the status bar in pixels, allowing you to override the value fetched by the SDK if needed.
  • setNavBarHeight(Int) - Specifies the height of the navigation bar in pixels, allowing you to override the value fetched by the SDK if needed.

Run your test script

Run your tests using either BrowserStack App Automate or your local XCode setup environment.

Run with App Automate

When you run the script on App Automate, proceed to generate the application IPA and the test suite IPA files. For the App Automate session to work with App Percy, we need to provide App Percy parameters.

For instance, in “appPercy”: {“env”: {“PERCY_BRANCH”: “test”}, “PERCY_TOKEN”: “"}, the env parameter can contain any of the following Percy environment variables.

Execute tests using the following command post updating App Percy params:

Run if using SCM integration

Run in local XCode setup

When you run the test script within a local XCode setup, continue modifying the test script by following the below steps:

1. Add 127.0.0.1 percy.cli to your /etc/hosts file on your macOS machine.
2. Open the terminal and set the Percy token: export PERCY_TOKEN=\<PERCY_TOKEN>.
3. Start your Percy server by running the following command:percy app:exec start.
4. Run your XCUI tests.
5. Stop your Percy server by running the following command:percy app:exec stop.