Skip to main content

Group Snapshots by Test Case Name

Explore App Percy’s test case grouping feature for streamlined snapshot organization.

In software testing, ensuring the accuracy and reliability of visual components across different environments and scenarios is paramount. One approach to achieving this is through the use of snapshots, which capture the visual state of an application at a specific point in time. However, managing and organizing these snapshots based on relevant test cases can be challenging for Quality Assurance (QA) professionals.

App Percy introduces a feature called ‘Group Snapshot by Test Case Name’ to address this challenge. The primary goal is to provide QAs with an efficient means to organize and categorize screenshots based on the associated test cases. This assists QAs in testing screenshots based on predefined test cases, facilitating an enhanced method for naming test cases and offering users greater flexibility and control over test case assignment. Users can explicitly define test cases associated with each screenshots by incorporating an additional argument in percyscreenshot function.


  • Streamlined Visual and Functional Testing: By associating snapshots with specific test cases, teams can efficiently track visual changes within the context of their functional tests. Utilizing test case-based grouping alongside synchronous comparison results further enhances this process, enabling real-time monitoring and management of visual changes within the context of functional tests.
  • Enhanced Organization: Allows Quality Assurance (QA) professionals to efficiently organize and categorize snapshots based on associated test cases, streamlining the testing process.
  • Improved Test Case Management: Provides greater flexibility and control over test case assignment, facilitating easier tracking and management of test cases associated with specific snapshots.

When using this feature, it is recommended to choose Visual Git as the baseline management method.

How to use

To use PercyScreenshot in your test cases, you must pass the test case name into a dictionary. This dictionary is a key-value pair where testCase is the key and the name of your test case is the value. The dictionary syntax depends on the language you use.

Here is an example of the PercyScreenshot syntax in Java:

percyScreenshot(login, { testCase: "testcase_name" })

For example, utilizing the syntax percyScreenshot(login, { testCase: "login case" }) creates a test case named “login Case” within the Percy dashboard. If the testCase argument is passed as percyScreenshot(login, { testCase: "login scenario" }), the test case assigned to that snapshot changes automatically. Subsequent builds will group snapshots under the “login scenario” test case name. Snapshots without a specified test case name will be grouped under the “Other” label for that build.

  • Each snapshot must have a unique combination of name and test case.
  • Currently, we do not support this feature for XCUI and Espresso frameworks.
Copy icon Copy snippet

Grouping filter

Percy provides grouping filters for grouping snapshots by Similar diffs and Test cases.

When filtering with Similar diffs, it groups snapshots with matching changes together. If Percy doesn’t find any matching differences in the build, it still displays individual snapshots.

When filtering with Test cases, it groups snapshots associated with test case names under their respective test case names, while the rest are grouped under label Other’.

App Percy Testcase and other label

How to access

Grouping Snapshots by Test Case Name streamlines the organization of snapshots, providing clarity and structure to the testing process. Follow these steps to access this feature:

  1. Go to your App Percy project.
  2. Click on the desired build.
  3. Use the Group snapshots by filter and select Test cases.

Builds screen having testcases information

The build screen lists the number of test cases along with their associated status.

Builds screen having testcases information

Test cases view

On the build screen, test cases are presented with clickable links that provide access to detailed information about each test case.

You can search for test cases using names, statuses, and labels. Additionally, you can switch tabs to view the ‘Changed’, ‘Unchanged’, and ‘Missing’ statuses for test cases.

Search test cases


You can review the test case history by clicking the ‘History’ link. This action opens a new screen listing the build number, build information, snapshots, and status of the selected test case, with the latest change displayed at the top.


Comparison Workflow

The approval workflow operates at the snapshot level when using test case based grouping. For example, if a snapshot is present in build 3, absent in build 2, and present in build 1, the relevant snapshot from build 3 will be compared against build 1, provided that the snapshot in build 1 has been approved. Comparisons are always conducted against the last approved snapshot.

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?


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