Several of Percy SDKs require you to pass in a string to name the snapshot you're taking. This document walks you through easy ways to generate these names in the most common JavaScript test frameworks.

The main requirements on a snapshot name string are:

1. It must be unique. Each snapshot in your test suite should have a different name.
2. It must remain stable between test runs. This is so that Percy can compare snapshot versions and catch any changes.

The code examples below assume that you're using the Percy Puppeteer SDK, but the instructions here would work for other Percy SDKs as well.

One snapshot per test case

If you are taking one snapshot per test case, a common strategy is to use the name of the test case as the name of the snapshot. Most JavaScript testing frameworks provide you with a method to access the name of the current test programmatically.

Mocha

In Mocha, you can access the properties of the currently-running test, including its full name, via the this.test object. Using this for naming a Percy snapshot would look like:

it('This is my test case name', async function() {
  // Some test stuff before snapshotting.
  percySnapshot(page, this.test.fullTitle())
})

Jasmine

For Jasmine versions before 2.0, you can use jasmine.getEnv().currentSpec to get the name of the current spec. Using that together with Percy would look like:

it('This is my test case name', function() {
  // Some test stuff before snapshotting.
  percySnapshot(page, jasmine.getEnv().currentSpec)
}

For Jasmine versions after 2.0, jasmine.getEnv().currentSpec is no longer supported. In these versions, you can get the current Jasmine spec name assigning your current it block to a variable and then querying it for its full name:

var mySpec = it('My test name that I want to get to', function() {
   // Some test stuff goes here.
   percySnapshot(page, mySpec.getFullName())
}

Cypress

If you're using the Percy Cypress SDK, Percy will automatically use the name of the current test for you if you don't pass in a snapshot name:

cy.percySnapshot()

If you want to access the test name yourself (for example, to manipulate it before passing it to Percy, or because you want to pass additional options), you can do so using cy.state('runnable').fullTitle():

cy.percySnapshot(cy.state('runnable').fullTitle())

Multiple snapshots per test case

In the cases when you are taking multiple Percy snapshots in the same test case, you can't rely entirely on using the test's name, as that will generate two different snapshots with the same name, and Percy will reject the second one.

In this situation, you can use an autogenerated snapshot name for the first call, and append a descriptive string to the autogenerated names for subsequent snapshot calls. For example, in Cypress:

it('My test with multiple snapshots', function() {
  // Do some testing
  cy.percySnapshot()  // Uses autogenerated name from test name
  // Do some more interacting with the page
  cy.percySnapshot(`${cy.state('runnable').fullTitle()} After Extra Stuff`)
})