How to test form validation with Cypress

Form validation isn’t just a checkbox to tick off before launch; it’s the gatekeeper of your app’s integrity. Allowing malformed or malicious input to slip through can result in corrupted data, security vulnerabilities, or just plain bad user experiences. Users expect forms to catch errors before submission, guiding them to fix what’s wrong rather than bombarding them with server errors.

Consider the difference between client-side and server-side validation. Client-side validation enhances user experience by providing immediate feedback, but server-side validation is your last line of defense. Never trust client-side checks alone because savvy users or bots can bypass them easily.

Validation covers a broad spectrum: required fields, proper formatting (like emails or phone numbers), constraints on length or character sets, and even cross-field dependencies. Each of these can be a potential pitfall if not handled correctly. For example, a simple “password confirmation” check can prevent a lot of frustration down the road.

Let’s look at a quick example of a simple JavaScript function that validates an email input:

function validateEmail(email) {
  const re = /^[^s@]+@[^s@]+.[^s@]+$/;
  return re.test(email);
}

This regular expression isn’t perfect, but it catches most common formatting issues. Pairing this with simple to operate error messages makes the form much more trustworthy.

Validation is more than just regex, though. Sometimes, you need to check if the input matches a value elsewhere or if a username is already taken. This means asynchronous checks, which complicate the UX and testing.

When you’re building validation logic, keep modularity in mind. Extract validation functions so they are testable independently. This practice not only improves code quality but also makes automated testing simpler, which brings us to Cypress.

Setting up Cypress for effective testing

Before writing tests with Cypress, you need to set up your environment correctly. Cypress requires Node.js, so make sure you have it installed. Then, you can add Cypress to your project with npm or yarn:

npm install cypress --save-dev

or

yarn add cypress --dev

Once installed, open Cypress for the first time to generate the default folder structure and example tests:

npx cypress open

This command launches the Cypress Test Runner and scaffolds a cypress/ directory with folders like integration, fixtures, and support. The integration folder is where your test specs live.

Configure your cypress.json file to set base URLs or environment variables that your tests will rely on. For example:

{
  "baseUrl": "http://localhost:3000",
  "viewportWidth": 1280,
  "viewportHeight": 720
}

Setting a baseUrl means you can use relative URLs in your tests, making them cleaner and easier to maintain.

To streamline tests that require authentication, use Cypress commands to abstract repetitive actions. Add custom commands in cypress/support/commands.js like this:

Cypress.Commands.add('login', (email, password) => {
  cy.request('POST', '/api/login', { email, password })
    .then((response) => {
      window.localStorage.setItem('authToken', response.body.token);
    });
});

Then, in your tests, you can simply call cy.login('[email protected]', 'password123') before visiting pages that require authentication.

It’s important to isolate form validation tests from other UI complexities. Use fixtures to mock backend responses or stub network requests to focus purely on client-side validation logic. For example, to stub a username availability check:

cy.intercept('GET', '/api/username/check?username=*', (req) => {
  if (req.query.username === 'takenUser') {
    req.reply({ statusCode: 200, body: { available: false } });
  } else {
    req.reply({ statusCode: 200, body: { available: true } });
  }
});

This lets you test how the form reacts to both available and taken usernames without hitting a real server.

Finally, organize your tests clearly. Use descriptive spec filenames like form-validation.spec.js, and group related validation tests using describe blocks to keep your suite maintainable:

describe('User Registration Form Validation', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  // tests go here
});

With Cypress set up this way, you’re ready to write tests that reliably catch validation issues before they reach production. Next, we’ll dive into some common validation scenarios and how to test them effectively.

Writing robust tests for common validation scenarios

Start by testing required fields. The simplest validation is ensuring users don’t submit empty inputs. Cypress makes this simpler by asserting error messages appear when inputs are left blank and the form is submitted.

describe('Required fields validation', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  it('shows error when required fields are empty', () => {
    cy.get('form').submit();
    cy.get('.error').should('contain', 'This field is required');
  });

  it('clears error when user types valid input', () => {
    cy.get('input[name="email"]').focus().blur();
    cy.get('.error').should('contain', 'This field is required');
    cy.get('input[name="email"]').type('[email protected]');
    cy.get('.error').should('not.exist');
  });
});

Next, test format validations like email or phone number. These typically use regex patterns or built-in HTML validation attributes. Your tests should input invalid data, check for error messages, and then input valid data to confirm errors disappear.

describe('Email format validation', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  it('rejects invalid email formats', () => {
    cy.get('input[name="email"]').type('invalid-email');
    cy.get('form').submit();
    cy.get('.error-email').should('contain', 'Please enter a valid email address');
  });

  it('accepts valid email formats', () => {
    cy.get('input[name="email"]').clear().type('[email protected]');
    cy.get('.error-email').should('not.exist');
  });
});

For cross-field validation, such as password confirmation, you want to verify that both fields match before allowing submission. This usually requires checking the error state updates dynamically as the user types.

describe('Password confirmation validation', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  it('shows error when passwords do not match', () => {
    cy.get('input[name="password"]').type('Password123!');
    cy.get('input[name="confirmPassword"]').type('Password321!');
    cy.get('form').submit();
    cy.get('.error-confirmPassword').should('contain', 'Passwords do not match');
  });

  it('removes error when passwords match', () => {
    cy.get('input[name="confirmPassword"]').clear().type('Password123!');
    cy.get('.error-confirmPassword').should('not.exist');
  });
});

Asynchronous validation, like checking username availability, requires stubbing API calls to simulate server responses. Use cy.intercept to mock these calls and verify the UI reacts accordingly.

describe('Username availability check', () => {
  beforeEach(() => {
    cy.intercept('GET', '/api/username/check?username=takenUser', {
      statusCode: 200,
      body: { available: false },
    }).as('checkUsername');

    cy.intercept('GET', '/api/username/check?username=freeUser', {
      statusCode: 200,
      body: { available: true },
    }).as('checkUsername');

    cy.visit('/register');
  });

  it('shows error if username is taken', () => {
    cy.get('input[name="username"]').type('takenUser');
    cy.wait('@checkUsername');
    cy.get('.error-username').should('contain', 'Username is already taken');
  });

  it('does not show error if username is available', () => {
    cy.get('input[name="username"]').clear().type('freeUser');
    cy.wait('@checkUsername');
    cy.get('.error-username').should('not.exist');
  });
});

Don’t forget to test boundary conditions like minimum and maximum input lengths. These are common sources of bugs especially when server constraints differ from client-side settings.

describe('Input length validation', () => {
  beforeEach(() => {
    cy.visit('/register');
  });

  it('rejects input shorter than minimum length', () => {
    cy.get('input[name="username"]').type('ab');
    cy.get('form').submit();
    cy.get('.error-username').should('contain', 'Username must be at least 3 characters');
  });

  it('rejects input longer than maximum length', () => {
    const longUsername = 'a'.repeat(51);
    cy.get('input[name="username"]').clear().type(longUsername);
    cy.get('form').submit();
    cy.get('.error-username').should('contain', 'Username cannot exceed 50 characters');
  });
});

Finally, test that the form only submits when all validations pass, and that the submission triggers the expected behavior like an API call or navigation. You can spy on network requests or UI changes to confirm this.

describe('Form submission', () => {
  beforeEach(() => {
    cy.intercept('POST', '/api/register', {
      statusCode: 201,
      body: { success: true },
    }).as('registerUser');

    cy.visit('/register');
  });

  it('submits form when all validations pass', () => {
    cy.get('input[name="username"]').type('validUser');
    cy.get('input[name="email"]').type('[email protected]');
    cy.get('input[name="password"]').type('Password123!');
    cy.get('input[name="confirmPassword"]').type('Password123!');
    cy.get('form').submit();

    cy.wait('@registerUser').its('response.statusCode').should('eq', 201);
    cy.url().should('include', '/welcome');
  });

  it('does not submit form if validations fail', () => {
    cy.get('form').submit();
    cy.get('@registerUser.all').should('have.length', 0);
  });
});