Skip to main content

Integrate your XCUITest test suite with App Percy

A guide to integrating your XCUITest automated tests with BrowserStack App Percy. Catch visual differences in your web application on time.

  • We support only XCTest.
  • We do not support XCTestPlan as no UI is rendered for XCTestPlan.

Integrate App Percy with your test suite to run visual tests. To do that, follow these steps:

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.

Create an App Percy project

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

Copy icon Copy snippet

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

The screenshot method arguments are:

Copy icon Copy snippet
  • 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:

Copy icon Copy snippet

Run if using SCM integration

Copy icon Copy snippet

Run in local XCode setup

When you run the test script within a local Android Studio environment, continue modifying the test script by adding the following code snippet, which adds the Percy Server address.

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 the /etc/hosts file on your macOS machine.
  2. Open the terminal and set the Percy token: Export 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.

If you encounter access restrictions to /etc/hosts file (e.g. Xcode Cloud), you can customize the hostname in the AppPercy class initializer. The default argument is “percy.cli”, but you can provide a different hostname to override it. This ensures smooth integration without disruption.

Congratulations!

You have successfully created your first build on App Percy. To see the build with snapshots of your application, visit your project in Percy.

When you run another build with visual changes to your application, Percy takes new snapshots. You can then see the comparisons between the two runs on the new build.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy