Testcafe Testing Library

Introduction

testcafe-testing-library allows the use of dom testing library queries within Testcafe for cross-browser end-to-end web testing.

If you are new to the testing-library approach for writing tests, check out the this guide on which query to use as well as the cheat sheet.

Install

npm install --save-dev testcafe @testing-library/testcafe

testcafe-testing-library on GitHub

Usage

testcafe-testing-library provides custom Selectors allowing you to query the dom.

Add the following to your .testcaferc.json file:

  "clientScripts": [
    { "module": "@testing-library/dom/dist/@testing-library/dom.umd.js" }
  ],

You can now import screen which has all the get[All]By, query[All]By, find[All]By* selectors that you can use in your tests.

import { screen } from '@testing-library/testcafe'

See DOM Testing Library API for reference

A note about queries in testcafe. Testcafe has built in waiting, for this reason, there's no difference between queryBy and findBy queries in testcafe testing library. getBy queries will throw an exception (as designed) so they will fail immediately and do not work with the built in waiting that Testcafe provides.

Examples

To show some simple examples (from https://github.com/testing-library/testcafe-testing-library/blob/master/tests/testcafe/selectors.ts):

import { screen } from '@testing-library/testcafe'

test('getByPlaceHolderText', async (t) => {
  await t.typeText(
    screen.getByPlaceholderText('Placeholder Text'),
    'Hello Placeholder'
  )
})
test('getByText', async (t) => {
  await t.click(screen.getByText('getByText'))
})

test('getByLabelText', async (t) => {
  await t.typeText(
    screen.getByLabelText('Label For Input Labelled By Id'),
    'Hello Input Labelled By Id'
  )
})

test('queryAllByText', async (t) => {
  await t.expect(screen.queryAllByText('Button Text').exists).ok()
  await t
    .expect(screen.queryAllByText('Non-existing Button Text').exists)
    .notOk()
})

Configure

You can customize the testIdAttribute using the configure function of DOM Testing Library in a few different ways:

Once in a single page load:

import { configureOnce, getByTestId } from '@testing-library/testcafe'

test('can be configured once in a single page load', async (t) => {
  await configureOnce({ testIdAttribute: 'data-other-test-id' })
  await t.click(screen.getByTestId('other-id'))
})

For every test & page load in a fixture:

import { configure, screen } from '@testing-library/testcafe'

fixture`configure`.clientScripts(
  configure({ testIdAttribute: 'data-automation-id' })
).page`http://localhost:13370`

test('supports alternative testIdAttribute', async (t) => {
  await t.click(screen.getByTestId('image-with-random-alt-tag'))
})

test('still works after browser page load and reload', async (t) => {
  await t.click(screen.getByText('Go to Page 2'))

  await t.eval(() => location.reload(true))

  await t
    .click(screen.getByTestId('page2-thing'))
    .expect(screen.getByText('second page').exists)
    .ok()
})

Globally for all fixtures, tests and page loads by injecting clientScripts

Note: the dom-testing-library umd must come before your configure script

.testcaferc.json

  "clientScripts": [
    "./node_modules/@testing-library/dom/dist/@testing-library/dom.umd.js",
    "./path/to/my-app-testcafe.config.js"
  ]

./path/to/my-app-testcafe.config.js

window.TestingLibraryDom.configure({ testIdAttribute: 'data-automation-id' })

Containers

By default the selectors come pre-bound to document.body, so no need to provide a container. However, if you want to restrict your query using a container, you can use within which can take either a string or a query (get[All]By, query[All]By, find[All]By*).

Examples using `within`

import { within, screen } from '@testing-library/testcafe'

fixture`within`.page`http://localhost:13370`

test('works with getBy* selectors', async (t) => {
  await t
    .expect(
      within(screen.getByTestId('nested')).getByText('Button Text').exists
    )
    .ok()
})

test('works with CSS selector strings', async (t) => {
  const { getByText } = await within('#nested')
  await t.click(getByText('Button Text')).ok()
})

test('works on any testcafe selector', async (t) => {
  const nested = Selector('#nested')

  await t.expect(within(nested).getByText('Button Text').exists).ok()
})

test('works with results from "byAll" query with index - regex', async (t) => {
  const nestedDivs = screen.getAllByTestId(/nested/)
  await t.expect(nestedDivs.count).eql(2)

  await t
    .expect(within(nestedDivs.nth(0)).getByText('Button Text').exists)
    .ok()
    .expect(
      within(nestedDivs.nth(1)).getByText('text only in 2nd nested').exists
    )
    .ok()
})

Introduction#

Install#

Usage#

Examples#

Configure#

Once in a single page load:#

For every test & page load in a fixture:#

Globally for all fixtures, tests and page loads by injecting clientScripts#

Containers#

Examples using within#