How can I catch unexpected error messages during Cypress test execution?

When using Cypress for end-to-end testing, we may encounter scenarios requiring the capture and handling of unexpected error messages. Cypress provides several methods to capture these errors, enabling us to handle them based on the requirements of the test cases.

Listening to Window Error Events

Cypress can listen to the error event on the window object to capture uncaught JavaScript errors. We can use the uncaught:exception event with Cypress.on or cy.on. For example:

javascript
// In the test script, you can set it up like this
Cypress.on('uncaught:exception', (err, runnable) => {
  // You can log the error for debugging
  console.error('Uncaught exception detected:', err);
  // Return false to prevent Cypress from failing
  return false;
});

This allows us to handle errors within the test script and decide whether to ignore specific errors, continue executing the test, or let the test fail.

Listening to the Application's onError Event

If we are testing a single-page application (SPA) that uses certain error handling mechanisms, such as window.onerror, we can set up listeners in the test to capture these errors:

javascript
cy.visit('http://example.com', {
  onBeforeLoad(win) {
    cy.spy(win, 'onerror');
  }
});

// Later, we can assert that onerror was called and the number of times
 cy.window().then((win) => {
   expect(win.onerror).to.have.callCount(1);
 });

Capturing Promise Exceptions in Test Code

When using cy.then() or other Cypress commands, we can directly capture and handle Promise exceptions within chained calls:

javascript
cy.get('.some-element').then(($element) => {
  return doSomethingThatReturnsAPromise($element).catch((err) => {
    // Handle the error
  });
});

Capturing Network Request Errors with cy.request

When using cy.request to make network requests to external APIs or services, we can directly capture request errors:

javascript
cy.request({
  url: 'http://example.com/api/data',
  failOnStatusCode: false // This prevents the test from failing if the response has a non-2xx status code
}).then((response) => {
  if (response.status !== 200) {
    // Handle the error response
  }
});

Example: Capturing Backend API Errors

Suppose we have a test case that needs to verify that users cannot log in with incorrect credentials:

javascript
// Login function using cy.request with failOnStatusCode set to false
function loginWithCredentials(username, password) {
  return cy.request({
    method: 'POST',
    url: '/api/login',
    body: { username, password },
    failOnStatusCode: false
  });
}

// Test case
describe('Login functionality', () => {
  it('should not allow login with incorrect credentials', () => {
    loginWithCredentials('incorrect_user', 'wrong_password').then((response) => {
      expect(response.status).to.eq(401); // Verify the response status code is 401 Unauthorized
      expect(response.body.error).to.include('Unauthorized'); // Verify the response body contains the specific error message
    });
  });
});

In this example, I used cy.request with failOnStatusCode: false, which allows the test to not fail immediately even if the API returns an error status code. This enables us to access the response object in the then callback to check the status code and response content, confirming that error handling is correct.