cypress-testing-library - Framework Patterns

Framework Mode - cypress-testing-library

Folder Structure

cypress-testing-library-project/
├── cypress/
│   ├── e2e/                  # Test specs using Cypress Testing Library
│   │   ├── login.cy.js       # Example test file
│   │   └── dashboard.cy.js
│   ├── support/              # Support commands and setup
│   │   ├── commands.js       # Custom Cypress commands
│   │   └── e2e.js            # Global setup for tests
│   └── fixtures/             # Test data files (JSON, etc.)
├── cypress.config.js         # Cypress configuration file
├── package.json              # Project dependencies and scripts
└── README.md

Test Framework Layers

• Test Specs (cypress/e2e): Contains test files using Cypress Testing Library queries to interact with UI elements by role, label, text, etc.
• Support Layer (cypress/support): Holds custom commands and global setup. Here you import and configure @testing-library/cypress to extend Cypress commands.
• Fixtures: Static test data files to keep test data separate from test logic.
• Configuration: The cypress.config.js file manages environment settings, base URLs, and browser options.

Configuration Patterns

• Environment Variables: Use cypress.env.json or env section in cypress.config.js to store credentials and environment-specific data securely.
• Base URL: Define baseUrl in cypress.config.js for easy switching between dev, staging, and production.
• Browser Selection: Configure browsers via CLI or cypress.config.js to run tests in Chrome, Firefox, or Edge.
• Setup Testing Library: Import @testing-library/cypress/add-commands in cypress/support/e2e.js to add Testing Library commands globally.

Test Reporting and CI/CD Integration

• Test Reports: Use Cypress built-in reporter or add plugins like mochawesome for detailed HTML reports.
• CI/CD Integration: Run Cypress tests in pipelines (GitHub Actions, GitLab CI, Jenkins) using npx cypress run.
• Artifacts: Save screenshots and videos on test failures for debugging.
• Parallelization: Use Cypress Dashboard service or CI parallel jobs to speed up test runs.

Best Practices

• Use Testing Library Queries: Prefer queries like getByRole, findByLabelText to select elements as a user would, improving test reliability.
• Keep Tests Independent: Each test should set up its own state and not rely on others.
• Custom Commands: Encapsulate repetitive actions in cypress/support/commands.js for reuse and clarity.
• Clear Test Data: Use fixtures and reset state between tests to avoid flaky results.
• Accessibility Focus: Testing Library encourages accessible selectors, promoting better app accessibility.

Self Check

Where in this framework structure would you add a new custom command to select a user profile button by its accessible name?

Key Result

Organize Cypress tests using Testing Library queries in e2e specs, configure commands in support, and manage environments in cypress.config.js.

Practice

1. What is the main benefit of using cypress-testing-library in your tests?

easy

A. It helps find elements like a user would, improving test readability.

B. It automatically fixes broken tests.

C. It replaces Cypress commands with JavaScript alerts.

D. It only works with CSS selectors.

Solution

1. Step 1: Understand the purpose of cypress-testing-library

   It is designed to find page elements by text, role, or label, mimicking how users interact with the page.

2. Step 2: Compare options with this purpose

   Only It helps find elements like a user would, improving test readability. correctly states that it helps find elements like a user would and improves test readability.

3. Final Answer:

   It helps find elements like a user would, improving test readability. -> Option A

4. Quick Check:

   User-focused element finding = A [OK]

Hint: Remember: testing-library = user-like element finding [OK]

Common Mistakes:

• Thinking it fixes tests automatically
• Confusing it with Cypress core commands
• Assuming it only uses CSS selectors

2. Which of the following is the correct syntax to find a button with the text 'Submit' using cypress-testing-library?

easy

A. cy.findByRole('button', { name: 'Submit' })

B. cy.findByText('Submit')

C. cy.get('button').contains('Submit')

D. cy.querySelector('button:contains("Submit")')

Solution

1. Step 1: Recall cypress-testing-library syntax for roles

   The recommended way is to use findByRole with the role and accessible name.

2. Step 2: Check each option

   cy.findByRole('button', { name: 'Submit' }) uses findByRole('button', { name: 'Submit' }), which is correct. cy.findByText('Submit') relies on text content without specifying the button role, making it less precise. cy.get('button').contains('Submit') uses Cypress core commands, not testing-library. cy.querySelector('button:contains("Submit")') is invalid syntax.

3. Final Answer:

   cy.findByRole('button', { name: 'Submit' }) -> Option A

4. Quick Check:

   Use findByRole with name for buttons = B [OK]

Hint: Use findByRole with name for accessible buttons [OK]

Common Mistakes:

• Using Cypress core commands instead of testing-library
• Missing the role parameter
• Using invalid selectors like querySelector

3. Given the code snippet:

cy.findByLabelText('Email').type('[e-mail]')
cy.findByRole('button', { name: 'Send' }).click()

What will happen when this test runs?

medium

A. It clicks the button but does not type the email.

B. It throws an error because findByLabelText does not exist.

C. It types the email but fails to find the button.

D. It types the email and clicks the 'Send' button successfully.

Solution

1. Step 1: Understand the commands used

   findByLabelText finds an input by its label text, and type enters text. findByRole finds a button by role and name, then click clicks it.

2. Step 2: Analyze the expected behavior

   Both commands are valid and should work if elements exist. So the test will type the email and click the button.

3. Final Answer:

   It types the email and clicks the 'Send' button successfully. -> Option D

4. Quick Check:

   Valid findByLabelText and findByRole = A [OK]

Hint: findByLabelText types, findByRole clicks [OK]

Common Mistakes:

• Assuming findByLabelText is invalid
• Confusing Cypress core commands with testing-library
• Thinking click happens before typing

4. You wrote this test:

cy.findByRole('textbox', { name: 'Username' }).type('admin')
cy.findByRole('button', { name: 'Login' }).click()

But the test fails with "Unable to find element" error on the textbox. What is the likely cause?

medium

A. The test is missing a wait() before typing.

B. The textbox does not have an accessible name 'Username'.

C. The type command is not supported on textboxes.

D. The button role is incorrect.

Solution

1. Step 1: Understand the error message

   "Unable to find element" means the locator did not find the textbox with role 'textbox' and name 'Username'.

2. Step 2: Check possible causes

   If the textbox lacks an accessible name 'Username', the locator fails. The button role is likely correct, and type works on textboxes. wait() is usually unnecessary.

3. Final Answer:

   The textbox does not have an accessible name 'Username'. -> Option B

4. Quick Check:

   Accessible name missing causes find failure = D [OK]

Hint: Check accessible names if findByRole fails [OK]

Common Mistakes:

• Assuming role or command is wrong
• Adding unnecessary waits
• Ignoring accessibility attributes

5. You want to test a form with multiple inputs labeled 'Name' but only one is visible at a time. Which cypress-testing-library method helps you select the visible input labeled 'Name' reliably?

hard

A. cy.findByLabelText('Name', { exact: false })

B. cy.findByLabelText('Name', { selector: ':visible' })

C. cy.findAllByLabelText('Name').filter(':visible').first()

D. cy.findByText('Name').filter(':visible')

Solution

1. Step 1: Identify the problem

   Multiple inputs share the same label 'Name', but only one is visible at a time.

2. Step 2: Choose method to select visible input

   findAllByLabelText returns all matching elements. Using filter(':visible') narrows to visible ones, and first() picks the first visible input.

3. Final Answer:

   cy.findAllByLabelText('Name').filter(':visible').first() -> Option C

4. Quick Check:

   Use findAll + filter visible + first = C [OK]

Hint: Use findAllByLabelText + filter(':visible') + first() [OK]

Common Mistakes:

• Using findByLabelText with invalid selector option
• Using findByText instead of label text
• Ignoring visibility filtering