handbook/api-testing/

[giscus[bot]]

handbook/api-testing/

Serenity/JS REST module provides the building blocks to help you automate interactions with HTTP-based

https://serenity-js.org/handbook/api-testing/

[tfarrar]

@jan-molak Do you have an sample template to show how to create a test scenario that uses rest API and Playwright together in the same scenario (i.e. it unit test).

We would like to speed up the testing by using backend rest APIs to create different configurations we need in the app and then check the UI displays the correct info in the right format.

To use the todo list as a example: Add all the items to the list via rest API, Then validate the UI shows those items.

[jan-molak]

Hey @tfarrar!

Sure, this sounds like a very reasonable use case. I'm planning to add a dedicated REST client to @serenity-js/playwright-test so that we can reuse the request object provided by Playwright - see #1876

For now, however, you can override the default actor injected by Serenity/JS to add the ability to CallAnApi which uses axios.

It would be something like this:

import { describe, it, test } from '@serenity-js/playwright-test'
import { Ensure, equals } from '@serenity-js/assertions'
import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'

import * as axios from 'axios'

describe('Todo List App', () => {

    test.use({
        actor: async ({ actor }, use) => {
    
          const axiosInstance = axios.create({
            timeout: 5 * 1000,
            headers: {
              'X-Custom-Api-Key': 'secret-key',
            },
          });
          
          await use(actor.whoCan(CallAnApi.using(axiosInstance))
        },
    })

    it('is up', async ({ actor }) => {

        await actor.attemptsTo(
            Send.a(GetRequest.to('https://example.org')),
            Ensure.that(LastResponse.status(), equals(200)),
        )
    })
})

You'll find more examples of using @serenity-js/rest in the API docs.

Does this help?

[tfarrar]

That helped a lot and will get me started.

Some obvious:

1. When running test the browser launched for api test will use headless normally.
2. I was not able to integrate api request with multiple ui actors. We have some test with different user type admin vs normal users.

This was a very good help to get us to get started on a lot of test changes.
Thank you
Tim

[jan-molak]

When running test the browser launched for api test will use headless normally.

Yes, you can set headless: true in playwright.config.ts to run the browser in headless mode

I was not able to integrate api request with multiple ui actors. We have some test with different user type admin vs normal users.

Sure, that's supported too. The example I showed you earlier is applicable to tests that use a single actor.

For tests that use multiple actors that need to be configured differently you should override the default Cast.

You can do it like this:

import { describe, it, test } from '@serenity-js/playwright-test'
import { Actor, Cast, Notepad, TakeNotes } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { CallAnApi } from '@serenity-js/rest'
import { Navigate, PageElements, By } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

import * as axios from 'axios'

describe('Todo List App', () => {

    test.use({
        actors: async ({ browser, contextOptions }, use) => {
    
            const cast = Cast.where((actor: Actor) => {
            
              // setup for admins
              if (actor.name === 'admin') {             
                const axiosInstance = axios.create({
                  timeout: 5 * 1000,
                  headers: {
                    'X-Custom-Api-Key': 'secret-key',
                  },
                })
              
                return actor.whoCan(
                  BrowseTheWebWithPlaywright.using(browser, {
                      ...contextOptions,
                      // custom overrides, if any
                  }),
                  TakeNotes.usingAnEmptyNotepad(),
                  CallAnApi.using(axiosInstance),
                )
              }
            
              // setup for regular users
              return actor.whoCan(
                BrowseTheWebWithPlaywright.using(browser, {
                    ...contextOptions,
                    // custom overrides, if any
                }),
                TakeNotes.usingAnEmptyNotepad(),
              )
            })
    
            await use(cast)
        },
    })


    it('is up', async ({ actorCalled }) => {

        await actorCalled('admin').attemptsTo(
            Send.a(GetRequest.to('https://example.org')),
            Ensure.that(LastResponse.status(), equals(200)),
        )
        
        await actorCalled('another actor').attemptsTo(
            // do something else
        )
    })
})

Does this help?