@nightwatch/testing-library

Using DOM Testing Library in Nightwatch has never been easier with the official Nightwatch plugin.

Requires Nightwatch 2.6.0 or higher.

---

• Installation
• Usage
• Contributors
• LICENSE

Installation

Install the project from NPM with:

npm i @nightwatch/testing-library --save-dev

Edit your nightwatch.json (or nightwatch.conf.js) file and add the plugin to the list:

{
  "plugins": [
    "@nightwatch/testing-library"      
  ]
}

Usage

Once the plugin is installed, you can use the TestingLibrary queries in your tests as regular Nightwatch commands.

About the queries

• getBy...: returns the matching element and throw a descriptive error if no elements match or if more than one match is found (use getAllBy instead if more than one element is expected);
• queryBy...: returns the matching element and return null if no elements match. This is useful for asserting an element that is not present. Throws an error if more than one match is found (use queryAllBy instead if this is OK);
• findBy...: same as getBy... but will retry until a default timeout of 1000ms is reached before throwing the error when no match is found. If you need to find more than one element, use findAllBy.

The complete list of queries is available on the DOM Testing Library documentation.

Returned values

The individual queries return a Nightwatch Element object. In addition to the element methods available directly on the element, you can use this object directly with any Nightwatch command or assertion that accepts an element as a parameter.

The getAllBy, findAllBy, queryAllBy queries return an array of Nightwatch Element objects.

The following are equivalent:

test('first example', async (browser) => {
  const input = await browser.getByLabelText('Label For Input Labelled By Id');
  await input.sendKeys('Hello Input Labelled by Id');
});

test('second example', async (browser) => {
  const input = await browser.getByLabelText('Label For Input Labelled By Id');
  await browser.sendKeys(input, 'Hello Input Labelled by Id');
});

getByText

test('getByText example', async function(browser) {
  const button = await browser.getByText('Unique Button Text');

  browser.click(button);
  browser.expect.element(button).text.to.equal('Button Clicked');
});

getByPlaceholderText

test('getByPlaceholderText example', async function(browser) {
  const input = await browser.getByPlaceholderText('Placeholder Text');

  // Uses the User Actions API to type into the input
  const webElement = await input.getWebElement();
  await browser.actions().sendKeys(webElement, 'Hello Placeholder').perform();

  await browser.expect.element(input).property('value').to.equal('Hello Placeholder');
});

getByLabelText

test('getByLabelText example', async function(browser) {
  const input = await browser.getByLabelText('Label For Input Labelled By Id');
  browser.sendKeys(input, 'Hello Input Labelled by Id');

  browser.expect.element(input).value.toEqual('Hello Input Labelled by Id');
});

getByAltText

test('getByAltText example', async function(browser) {
  const image = await browser.getByAltText('Image Alt Text');

  browser.expect.element(image).to.be.present;
});

getByTestId

test('getByTestId example', async function(browser) {
  const button = await browser.getByTestId('unique-button-id');

  browser.click(button);
  browser.expect.element(button).text.to.equal('Button Clicked');
});

getAllByText

test('getAllByText example', async function(browser) {
  const chans = await browser.getAllByText('Jackie Chan', {exact: false});
  browser.expect(chans).to.have.length(2);
});

getAllByText with regex

test('getAllByText with regex example', async function(browser) {
  const chans = await browser.getAllByText(/Jackie Chan/)
  browser.expect(chans).to.have.length(2);
});

queryAllByText

test('queryAllByText', async function (browser) {
  const buttons = await browser.queryAllByText('Button Text');
  const nonExistentButtons = await browser.queryAllByText('non existent button');

  browser.expect(buttons).to.have.length(2);
  browser.expect(nonExistentButtons).to.have.length(0);
});

using .within

test('getByText within container', async browser => {
  const nested = await browser.getByTestId('nested');
  const button = await browser.within(nested).getByText('Button Text');

  await browser.click(button);
  await browser.expect.element(button).text.to.equal('Button Clicked');
});

test('using nested selector from "All" query with index - regex', async browser => {
  const nestedDivs = await browser.getAllByTestId(/nested/);

  await browser.expect(nestedDivs).to.have.length(2)

  const nested = browser.within(nestedDivs[1]);
  const button = await nested.getByText('Button Text');
  const text = await nested.getByText('text only in 2nd nested');

  await browser.expect.element(button).to.be.present;
  await browser.expect.element(text).to.be.present;
});

Configure testIdAttribute

The testIdAttribute can be configured to use a different attribute for the getByTestId query

1. In your nightwatch.json (or nightwatch.conf.js) file:

{
  "testing_library": {
    "testIdAttribute": "data-automation-id"
  }
}

2. In your test file:

describe('configure test', function () {

  this.settings.testing_library = {
    testIdAttribute: 'data-automation-id'
  };

  beforeEach(browser => browser.url('http://localhost:13370'));

  test('supports alternative test Id attribute', async (browser) => {
    const image = await browser.getByTestId('image-with-random-alt-tag');
    browser.click(image);
    browser.expect.element(image).to.have.css('border').which.equals('5px solid rgb(255, 0, 0)')
  });
});

Contributors

Thanks goes to these wonderful people (emoji key):

Ben Monro 📖 💻 ⚠️ 🚇 🤔

Kent C. Dodds 🚇 🤔 💻

Kevin Brewer 🤔 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT