Vue.js Cypress Testing

Introduction

End-to-end testing is a crucial part of modern web application development, and when it comes to Vue.js applications, Cypress has emerged as one of the most popular and developer-friendly testing tools. Unlike unit tests that verify individual components in isolation, end-to-end tests validate the entire application flow from a user's perspective.

Cypress is a JavaScript-based end-to-end testing framework that runs directly in the browser, providing real-time feedback as tests execute. It allows you to write tests that simulate user interactions like clicking buttons, filling forms, and navigating between pages, all while making assertions about what should appear in your application.

In this guide, we'll explore how to set up Cypress in a Vue.js project, write effective tests, and implement best practices for reliable test suites.

Why Use Cypress with Vue.js?

Cypress offers several advantages that make it particularly well-suited for testing Vue.js applications:

Real browser environment: Tests run in the same browser environment users experience
Time-travel debugging: See exactly what happened at each step of your tests
Automatic waiting: No more explicit waits or sleep statements
Modern API: Simple, readable syntax for test assertions
Vue.js DevTools integration: Examine Vue component state during tests
Interactive test runner: Visual interface for running and debugging tests

Setting Up Cypress in a Vue.js Project

Step 1: Install Cypress

If you're using Vue CLI, you can install the official @vue/cli-plugin-e2e-cypress plugin:

bash
vue add e2e-cypress

For a manual installation in any Vue.js project:

bash
npm install cypress --save-dev

or using yarn:

bash
yarn add cypress --dev

Step 2: Configure Cypress

After installation, you'll need to set up your Cypress configuration. If you used Vue CLI, most of this is done for you.

For manual installations, add these scripts to your package.json:

json
{
  "scripts": {
    "cypress:open": "cypress open",
    "cypress:run": "cypress run"
  }
}

Then initialize Cypress by running:

bash
npx cypress open

This creates a cypress directory in your project with the following structure:

cypress/
  ├── fixtures/       # Test data files
  ├── integration/    # Test files
  ├── plugins/        # Plugin configuration
  ├── support/        # Support code and custom commands
  └── videos/         # Recorded test videos

Step 3: Configure Base URL

Create or update your cypress.json file in the project root:

json
{
  "baseUrl": "http://localhost:8080",
  "viewportWidth": 1280,
  "viewportHeight": 800
}

Adjust the baseUrl to match your Vue development server address.

Writing Your First Cypress Test

Let's create a simple test that checks if our Vue application loads correctly. Create a file called home_page_spec.js in the cypress/integration folder:

javascript
describe('Home Page', () => {
  beforeEach(() => {
    // Visit the base URL before each test
    cy.visit('/')
  })

  it('loads the home page successfully', () => {
    // Verify that the page contains some expected element
    cy.contains('h1', 'Welcome to Your Vue.js App')
  })
  
  it('has navigation menu', () => {
    // Check if navigation exists
    cy.get('nav').should('be.visible')
  })
})

Running Your Test

Start your Vue development server:

bash
npm run serve

Then in a separate terminal, run Cypress:

bash
npm run cypress:open

This opens the Cypress Test Runner where you can click on your home_page_spec.js file to run the tests.

Testing Vue.js Components

One of the strengths of Cypress is the ability to interact with and test Vue.js components in the same way a user would.

Example: Testing a Counter Component

Let's say we have a simple counter component:

html
<template>
  <div class="counter">
    <p data-cy="count">{{ count }}</p>
    <button data-cy="increment" @click="increment">Increment</button>
    <button data-cy="decrement" @click="decrement">Decrement</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    },
    decrement() {
      this.count--
    }
  }
}
</script>

Notice the data-cy attributes - these are helpful selectors for Cypress tests.

Now let's write a test for this component. Create a file called counter_spec.js in your Cypress integration folder:

javascript
describe('Counter Component', () => {
  beforeEach(() => {
    // Visit the page that contains the counter component
    cy.visit('/counter')
  })

  it('displays initial count of zero', () => {
    cy.get('[data-cy=count]').should('have.text', '0')
  })

  it('increments the counter when increment button is clicked', () => {
    cy.get('[data-cy=increment]').click()
    cy.get('[data-cy=count]').should('have.text', '1')
  })

  it('decrements the counter when decrement button is clicked', () => {
    cy.get('[data-cy=decrement]').click()
    cy.get('[data-cy=count]').should('have.text', '-1')
  })

  it('correctly handles multiple clicks', () => {
    cy.get('[data-cy=increment]').click().click().click()
    cy.get('[data-cy=count]').should('have.text', '3')
    
    cy.get('[data-cy=decrement]').click()
    cy.get('[data-cy=count]').should('have.text', '2')
  })
})

Testing Form Interactions

Forms are a common element in web applications. Let's see how to test a simple login form:

javascript
describe('Login Form', () => {
  beforeEach(() => {
    cy.visit('/login')
  })

  it('submits the form with valid data', () => {
    // Type in form fields
    cy.get('[data-cy=email]').type('[email protected]')
    cy.get('[data-cy=password]').type('password123')
    
    // Submit form
    cy.get('[data-cy=login-button]').click()
    
    // Assert that login was successful
    cy.url().should('include', '/dashboard')
    cy.get('[data-cy=welcome-message]').should('contain', 'Welcome, User')
  })

  it('shows validation errors for empty fields', () => {
    // Submit empty form
    cy.get('[data-cy=login-button]').click()
    
    // Check for validation error messages
    cy.get('[data-cy=email-error]').should('be.visible')
    cy.get('[data-cy=password-error]').should('be.visible')
  })
})

Advanced Techniques

Working with API Requests

Cypress allows you to stub API responses, which is useful for testing different scenarios without depending on a real backend:

javascript
describe('Products Page', () => {
  it('displays products from API', () => {
    // Intercept API call and provide mock data
    cy.intercept('GET', '/api/products', {
      statusCode: 200,
      body: [
        { id: 1, name: 'Product 1', price: 10.99 },
        { id: 2, name: 'Product 2', price: 24.99 },
        { id: 3, name: 'Product 3', price: 5.99 }
      ]
    }).as('getProducts')
    
    cy.visit('/products')
    cy.wait('@getProducts')
    
    // Verify products are displayed
    cy.get('[data-cy=product-card]').should('have.length', 3)
    cy.contains('Product 2').should('be.visible')
  })

  it('handles API errors gracefully', () => {
    // Simulate API error
    cy.intercept('GET', '/api/products', {
      statusCode: 500,
      body: { error: 'Server error' }
    }).as('getProductsError')
    
    cy.visit('/products')
    cy.wait('@getProductsError')
    
    // Verify error message is shown
    cy.get('[data-cy=error-message]')
      .should('be.visible')
      .and('contain', 'Failed to load products')
  })
})

Testing Vuex Store Actions

You can also test interactions with your Vuex store:

javascript
describe('Shopping Cart', () => {
  beforeEach(() => {
    // Reset the cart before each test
    cy.window().then((win) => {
      win.app.$store.commit('cart/RESET_CART')
    })
    cy.visit('/products')
  })

  it('adds items to cart and updates count', () => {
    // Add first product to cart
    cy.get('[data-cy=add-to-cart]').first().click()
    
    // Check cart count updated
    cy.get('[data-cy=cart-count]').should('have.text', '1')
    
    // Add another item
    cy.get('[data-cy=add-to-cart]').eq(1).click()
    cy.get('[data-cy=cart-count]').should('have.text', '2')
    
    // Visit cart page and verify items
    cy.visit('/cart')
    cy.get('[data-cy=cart-item]').should('have.length', 2)
  })
})

Custom Cypress Commands

Creating custom Cypress commands can help reduce code duplication in your tests. Add these to your cypress/support/commands.js file:

javascript
// Login command
Cypress.Commands.add('login', (email, password) => {
  cy.visit('/login')
  cy.get('[data-cy=email]').type(email)
  cy.get('[data-cy=password]').type(password)
  cy.get('[data-cy=login-button]').click()
})

// Add to cart command
Cypress.Commands.add('addToCart', (productIndex) => {
  cy.visit('/products')
  cy.get('[data-cy=add-to-cart]').eq(productIndex).click()
})

Then use them in your tests:

javascript
describe('Checkout Flow', () => {
  beforeEach(() => {
    cy.login('[email protected]', 'password123')
    cy.addToCart(0) // Add first product
  })

  it('completes checkout process', () => {
    cy.visit('/cart')
    cy.get('[data-cy=checkout-button]').click()
    // Continue with checkout test...
  })
})

Best Practices for Vue.js Cypress Testing

Use data-cy attributes: Add specific selectors to important elements for testing.

html
<template>
  <button data-cy="submit-button" @click="submitForm">Submit</button>
</template>

Test user flows, not implementation details: Focus on what users do, not how components work internally.
Keep tests independent: Each test should work in isolation without depending on others.
Mock API responses: Use cy.intercept() to control backend responses for consistent tests.
Use fixtures for test data: Store complex test data in JSON files in the cypress/fixtures folder.
Organize tests logically: Group tests by feature or page for better organization.
Wait for Vue to render: Sometimes you need to ensure Vue has updated the DOM:

javascript
// Wait for Vue to update DOM before continuing
cy.get('[data-cy=loading-indicator]').should('not.exist')

Avoid timing issues: Use assertions rather than arbitrary waits to synchronize your tests.

Real-World Example: Testing a Todo App

Let's create a complete example for testing a Vue todo application:

javascript
describe('Todo App', () => {
  beforeEach(() => {
    // Reset todos before each test
    cy.intercept('GET', '/api/todos', { body: [] }).as('getTodos')
    cy.visit('/')
    cy.wait('@getTodos')
  })

  it('adds a new todo', () => {
    // Setup API mock to catch the POST
    cy.intercept('POST', '/api/todos', {
      statusCode: 201,
      body: { id: 1, text: 'Learn Cypress', completed: false }
    }).as('addTodo')
    
    // Type and submit a new todo
    cy.get('[data-cy=new-todo]').type('Learn Cypress')
    cy.get('[data-cy=add-todo]').click()
    
    // Wait for the API call and verify the todo appears
    cy.wait('@addTodo')
    cy.get('[data-cy=todo-item]').should('have.length', 1)
    cy.contains('Learn Cypress').should('be.visible')
  })

  it('marks a todo as completed', () => {
    // Setup API with initial todo
    cy.intercept('GET', '/api/todos', {
      body: [{ id: 1, text: 'Learn Cypress', completed: false }]
    }).as('getTodos')
    
    cy.intercept('PATCH', '/api/todos/1', {
      statusCode: 200,
      body: { id: 1, text: 'Learn Cypress', completed: true }
    }).as('updateTodo')
    
    cy.visit('/')
    cy.wait('@getTodos')
    
    // Mark todo as complete
    cy.get('[data-cy=todo-checkbox]').click()
    cy.wait('@updateTodo')
    
    // Verify the UI shows it as completed
    cy.get('[data-cy=todo-item]').should('have.class', 'completed')
  })

  it('filters todos correctly', () => {
    // Setup API with multiple todos
    cy.intercept('GET', '/api/todos', {
      body: [
        { id: 1, text: 'Learn Cypress', completed: true },
        { id: 2, text: 'Write tests', completed: false }
      ]
    }).as('getTodos')
    
    cy.visit('/')
    cy.wait('@getTodos')
    
    // Check all todos are visible initially
    cy.get('[data-cy=todo-item]').should('have.length', 2)
    
    // Filter active todos
    cy.get('[data-cy=filter-active]').click()
    cy.get('[data-cy=todo-item]').should('have.length', 1)
    cy.contains('Write tests').should('be.visible')
    cy.contains('Learn Cypress').should('not.exist')
    
    // Filter completed todos
    cy.get('[data-cy=filter-completed]').click()
    cy.get('[data-cy=todo-item]').should('have.length', 1)
    cy.contains('Learn Cypress').should('be.visible')
    cy.contains('Write tests').should('not.exist')
  })
})

Using Cypress with Vue Router

When testing a Vue.js application with Vue Router, you might want to test navigation and route-based behavior:

javascript
describe('Navigation', () => {
  it('navigates between routes', () => {
    cy.visit('/')
    
    // Click navigation link
    cy.get('[data-cy=nav-about]').click()
    
    // Verify URL changed
    cy.url().should('include', '/about')
    
    // Verify about page content loaded
    cy.get('[data-cy=about-header]').should('be.visible')
  })

  it('handles protected routes', () => {
    cy.visit('/dashboard')
    
    // Should be redirected to login when not authenticated
    cy.url().should('include', '/login')
    
    // Login
    cy.login('[email protected]', 'password123')
    
    // Try accessing dashboard again
    cy.visit('/dashboard')
    
    // Should now be on dashboard
    cy.url().should('include', '/dashboard')
    cy.get('[data-cy=dashboard-welcome]').should('be.visible')
  })
})

Debugging Cypress Tests

Cypress provides powerful debugging tools:

Time travel: Click on any command in the command log to see the application state at that point
Debug command: Use cy.debug() to pause execution and inspect state in the console

javascript
it('debugs a test', () => {
  cy.visit('/')
  cy.get('[data-cy=complex-element]').debug()
  cy.get('[data-cy=next-element]').click()
})

Screenshots and videos: Cypress automatically captures screenshots on failures and can record videos of test runs
Console logs: Use cy.log() to add messages to the command log

javascript
cy.log('About to submit form')
cy.get('form').submit()

Summary

In this guide, we covered how to set up Cypress in a Vue.js application and create effective end-to-end tests. We learned how to:

Install and configure Cypress in a Vue.js project
Write basic tests for Vue components
Test form interactions and submissions
Use advanced techniques like API mocking
Implement best practices for Vue.js testing
Create custom Cypress commands
Debug tests when issues occur

End-to-end testing with Cypress helps ensure that your Vue.js application works correctly from a user's perspective. By writing comprehensive tests, you can catch bugs early and confidently refactor your code, knowing that your tests will alert you to any regressions.

Additional Resources

Exercises

Set up Cypress in an existing Vue.js project and write a test for the home page
Create a test for a form that includes validation and submission
Write a test that mocks an API response and verifies that your component handles it correctly
Implement custom Cypress commands for common actions in your application
Write a test suite for a multi-step process like a checkout or registration flow

By practicing these exercises, you'll gain confidence in your Cypress testing skills and improve the reliability of your Vue.js applications.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

Why Use Cypress with Vue.js?​

Setting Up Cypress in a Vue.js Project​

Step 1: Install Cypress​

Step 2: Configure Cypress​

Step 3: Configure Base URL​

Writing Your First Cypress Test​

Running Your Test​

Testing Vue.js Components​

Example: Testing a Counter Component​

Testing Form Interactions​

Advanced Techniques​

Working with API Requests​

Testing Vuex Store Actions​

Custom Cypress Commands​

Best Practices for Vue.js Cypress Testing​

Real-World Example: Testing a Todo App​

Using Cypress with Vue Router​

Debugging Cypress Tests​

Summary​

Additional Resources​

Exercises​