Percy integration basics in Cypress - Framework Patterns

Framework Mode - Percy integration basics

Folder Structure

cypress/
├── e2e/                  # Test specs
│   └── visual.spec.js    # Visual test example
├── support/              # Support commands and setup
│   ├── commands.js       # Custom Cypress commands
│   └── e2e.js            # Global setup for tests
cypress.config.js         # Cypress configuration file
package.json             # Project dependencies and scripts
.percy.yml               # Percy configuration file

Test Framework Layers

• Test Specs (cypress/e2e): Write Cypress tests here. Include Percy snapshots to capture visual states.
• Support Layer (cypress/support): Add custom commands and global test setup. Initialize Percy commands here.
• Configuration: Manage Cypress and Percy settings in cypress.config.js and .percy.yml.
• Utilities: Helper functions or data can be added in support or separate utils folder if needed.

Configuration Patterns

• cypress.config.js: Configure base URL, test retries, and include Percy plugin setup.
• .percy.yml: Define Percy project settings like widths, minimum height, and ignore regions.
• Environment Variables: Use CYPRESS_BASE_URL and PERCY_TOKEN to keep credentials and URLs secure and flexible.
• Package.json scripts: Add scripts to run tests with Percy enabled, e.g., cypress run with Percy environment variables.

Test Reporting and CI/CD Integration

• Percy Dashboard: Visual test results appear here with diffs highlighted for UI changes.
• CI/CD Pipelines: Integrate Percy by setting PERCY_TOKEN in CI environment variables and running Cypress tests with Percy enabled.
• Test Reports: Use Cypress reporters for functional test results alongside Percy visual reports.
• Fail Builds on Visual Changes: Configure CI to fail if Percy detects unexpected visual diffs.

Best Practices

1. Take snapshots at meaningful UI states to catch visual regressions early.
2. Keep snapshots small and focused to reduce noise and speed up tests.
3. Use environment variables to keep tokens and URLs secure and flexible across environments.
4. Integrate Percy in CI/CD to automate visual testing on every code change.
5. Review Percy diffs carefully to avoid false positives and maintain UI quality.

Self Check

Where in this folder structure would you add a new visual test for the homepage using Percy snapshots?

Key Result

Organize Cypress tests with Percy snapshots in e2e folder, configure with cypress.config.js and .percy.yml, and integrate visual testing into CI/CD pipelines.

Practice

1. What is the main purpose of integrating Percy with Cypress tests?

easy

A. To speed up test execution time

B. To catch visual bugs by taking screenshots during tests

C. To generate test data automatically

D. To write unit tests for backend APIs

Solution

1. Step 1: Understand Percy's role in testing

   Percy is used to capture screenshots during tests to detect visual changes.

2. Step 2: Compare options with Percy's purpose

   Only To catch visual bugs by taking screenshots during tests matches Percy's function of catching visual bugs via screenshots.

3. Final Answer:

   To catch visual bugs by taking screenshots during tests -> Option B

4. Quick Check:

   Percy purpose = Visual bug detection [OK]

Hint: Percy = visual snapshots during tests [OK]

Common Mistakes:

• Thinking Percy speeds up tests
• Confusing Percy with test data tools
• Assuming Percy writes backend tests

2. Which of the following is the correct syntax to take a Percy snapshot in a Cypress test?

easy

A. percy.cySnapshot('Homepage')

B. cy.snapshotPercy('Homepage')

C. cy.percySnapshot('Homepage')

D. cy.takePercySnapshot('Homepage')

Solution

1. Step 1: Recall Percy snapshot command syntax

   The correct command is cy.percySnapshot('name') to capture snapshots.

2. Step 2: Match options with correct syntax

   Only cy.percySnapshot('Homepage') matches the exact syntax cy.percySnapshot('Homepage').

3. Final Answer:

   cy.percySnapshot('Homepage') -> Option C

4. Quick Check:

   Correct Percy command = cy.percySnapshot() [OK]

Hint: Look for exact cy.percySnapshot() syntax [OK]

Common Mistakes:

• Swapping method and object order
• Adding extra words like 'take'
• Using wrong method names

3. Given this Cypress test snippet with Percy integration:

describe('Visual test', () => {
  it('checks homepage', () => {
    cy.visit('/')
    cy.percySnapshot('Homepage loaded')
    cy.get('#login').click()
    cy.percySnapshot('Login clicked')
  })
})

How many Percy snapshots will be captured during this test run?

medium

A. 1

B. 3

C. 0

D. 2

Solution

1. Step 1: Count cy.percySnapshot calls in the test

   There are two calls: one after visiting homepage, one after clicking login.

2. Step 2: Confirm each call triggers a snapshot

   Each cy.percySnapshot() call captures one snapshot, so total is 2.

3. Final Answer:

   2 -> Option D

4. Quick Check:

   Number of snapshots = 2 [OK]

Hint: Count cy.percySnapshot() calls in test [OK]

Common Mistakes:

• Counting only one snapshot
• Assuming snapshots auto-capture without calls
• Confusing clicks with snapshots

4. You wrote this Cypress test with Percy snapshot:

it('checks page', () => {
  cy.visit('/page')
  cy.percySnapshot()
})

But Percy dashboard shows no snapshots. What is the likely problem?

medium

A. Missing snapshot name argument in cy.percySnapshot()

B. cy.visit() must be called after cy.percySnapshot()

C. Percy snapshots only work on mobile viewport

D. You must call cy.percySnapshot() twice per test

Solution

1. Step 1: Check cy.percySnapshot usage

   The cy.percySnapshot() command requires a name string argument to identify the snapshot.

2. Step 2: Identify missing argument issue

   Since no name is given, Percy does not capture or upload the snapshot.

3. Final Answer:

   Missing snapshot name argument in cy.percySnapshot() -> Option A

4. Quick Check:

   Snapshot name required = true [OK]

Hint: Always provide a name string to cy.percySnapshot() [OK]

Common Mistakes:

• Thinking visit order matters
• Believing Percy only works on mobile
• Assuming multiple snapshots are mandatory

5. You want to test a form with Percy snapshots at three steps: before filling, after filling, and after submission. Which code snippet correctly integrates Percy snapshots in Cypress?

hard

A. cy.visit('/form')
cy.percySnapshot('Before filling')
cy.get('#input').type('data')
cy.percySnapshot('After filling')
cy.get('#submit').click()
cy.percySnapshot('After submission')

B. cy.visit('/form')
cy.percySnapshot()
cy.get('#input').type('data')
cy.percySnapshot()
cy.get('#submit').click()
cy.percySnapshot()

C. cy.visit('/form')
cy.get('#input').type('data')
cy.percySnapshot('After filling')
cy.get('#submit').click()

D. cy.visit('/form')
cy.get('#submit').click()
cy.percySnapshot('After submission')

Solution

1. Step 1: Identify required Percy snapshots

   Snapshots needed at three steps: before filling, after filling, after submission.

2. Step 2: Check which snippet has all three snapshots with names

   Only cy.visit('/form') cy.percySnapshot('Before filling') cy.get('#input').type('data') cy.percySnapshot('After filling') cy.get('#submit').click() cy.percySnapshot('After submission') has three named cy.percySnapshot() calls at correct steps.

3. Final Answer:

   Code snippet with three named Percy snapshots at correct steps -> Option A

4. Quick Check:

   Three named snapshots = cy.visit('/form') cy.percySnapshot('Before filling') cy.get('#input').type('data') cy.percySnapshot('After filling') cy.get('#submit').click() cy.percySnapshot('After submission') [OK]

Hint: Name each snapshot and place at correct test steps [OK]

Common Mistakes:

• Omitting snapshot names
• Missing snapshots at required steps
• Calling snapshots before visit