Cypress is a great tool for API testing, but the out-of-the-box test runner is lacking some detail that could be useful when building API tests and troubleshooting issues.

The good news is that Cypress is extensible, and has a large active user community. cy-api from Gleb Bahmutov is one of those extensions, and it puts lots of valuable API-related information at your fingertips.

If you want a more detailed walk-through on getting started with Cypress API testing, I have another post that can help you with that.

So let's take a look at cy-api!

Setup

To run my sample tests you can pull my repo and run "npm install" to install the dependencies. If you check the "package.json" file, you'll see that one of the dependencies is "@bahmutov/cy-api":.

With this project we'll create an "/employees" endpoint using json-server. To start that endpoint, just run:

json-server employees.js

You should now have an endpoint at http://localhost:3000/employees that serves up a list of employees.

running API tests with cy.request

cy.request is core Cypress functionality you can use to run your API tests. The Cypress test I created that uses this functionality can be found in my project at "cypress/integration/cy-request-spec.js".

There are a couple of tests in this spec file and they make calls to the "http://localhost:3000/employees" endpoint using "cy.request". For example, the first test:

it('get all the employees', () => {
    cy
      .request(
        {
          url: 'http://localhost:3000/employees/'
        }
      )
      .then((response) => {
        expect(response.status).to.eq(200)
        expect(response.headers['content-type']).to.include('application/json')
        expect(response.body).to.have.length(50)
      })
  })

Let's run this test.

Start the Cypress runner with "npx cypress open" and run "cy-request-spec.js". For test "employees API test with cy.request", expand the "get all the employees" test. You'll see something like this:

In the left panel you can see some info about the request, and info about the asserts. The panel to the right will usually show the browser DOM. Since our API test has no UI, we get nothing here.

We also don't see any specifics about the response. What specific data was sent and returned? How was it formatted? That info is not available here.

Click the request in the left panel.

OK that gave us nothing new, hmmmm. Let's see what we get with cy.api.

running API tests with cy.api

Take a look at the 2nd test in our project "cy-api-spec.js". This is identical to our first test except I have replaced "cy.request" with "cy.api".

Run this test in the Cypress test runner and expand the first test "get all the employees". Now instead of seeing a "request" line in the TEST BODY, we see 2 lines, "api" and "response":

Click each, and you'll see the full API request and response in the right panel. Nice!

Expand the 2nd test, "add and delete an employee". This test has 4 API calls: POST, GET, DELETE, GET. Take a look at the request and response for the POST. You can see the data sent and received.

This may seem minor, but think how useful info like this will be if you are trying to build tests and troubleshoot issues.

Wrap-up

So that's it. I just wanted to share a cool little tool that you might want to use with your Cypress API testing. Let me know your thoughts or suggestions.

Feel free to subscribe to my blog site for more test automation content. Thanks!