🎭 Playwright Node.js

How to setup and use Playwright (minimum setup)

Creating Node.js project

• Install Node.js
• Install Yarn
• Create a new empty folder.

  $ mkdir playwright-getting-started
  $ cd playwright-getting-started

• Create a new Node.js project with default configuration.

  $ yarn init -y

• Install required Node packages. We will use TypeScript and ts-jest in this project.

  $ yarn add -D \
    @types/jest \
    add \
    jest \
    playwright \
    ts-jest \
    typescript

• Open package.json with your favorite text editor and you will find the content like as following code.

  {
    "name": "playwright-getting-started",
    "version": "1.0.0",
    "main": "index.js",
    "license": "MIT",
    "devDependencies": {
      "@types/jest": "^26.0.22",
      "jest": "^26.6.3",
      "playwright": "^1.10.0",
      "ts-jest": "^26.5.4",
      "typescript": "^4.2.3"
    }
  }

• Please be informed that you may get a newer version of NPM packages.

Configure Jest

• Create jest.config.js at the root folder of your project and configure it to use ts-jest preset with the following code:

  // jest.config.js
  module.exports = {
    preset: 'ts-jest',
    testEnvironment: 'node',
  };

Writing your first test case

• Create a folder src/__tests__ and add homepage.test.ts to the folder.

• Add test contents to homepage.test.ts with the following code:

  // src/__tests__/homepage.test.ts
  import { chromium } from 'playwright';
  // Use uppercase name for a test suite.
  describe('Homepage', () => {
    // Use lowercase name for a test case.
    test('should launch homepage with expected title', async () => {
      const browser = await chromium.launch();
      const context = await browser.newContext();
      const page = await context.newPage();
      await page.goto('https://todomvc.com');
      const pageTitle = await page.title();
      expect(pageTitle).toBe('TodoMVC');
      await browser.close();
    });
  });

• This test will launch http://todomvc.com with a headless Chromium.

• Verify if a page's title matches TodoMVC value.

• By default, Playwright will launch in headless mode so you won't see UI of a browser.

• You can make Playwright launch a UI browser by setting chromium.launch({ headless: false }) option.

Adding custom script to your package.json

• Add a custom script with the following content to to your package.json.

  "scripts": {
    "test": "jest"
  },

• Then you will find the latest package.json looks like this:

  {
    "name": "playwright-getting-started",
    "version": "1.0.0",
    "main": "index.js",
    "license": "MIT",
    "scripts": {
      "test": "jest"
    },
    "devDependencies": {
      "@types/jest": "^26.0.22",
      "jest": "^26.6.3",
      "playwright": "^1.10.0",
      "ts-jest": "^26.5.4",
      "typescript": "^4.2.3"
    }
  }

Checking the project file structure

• Here is the file structure in our project.

  $ tree -I "node_modules" playwright-getting-started/
  playwright-getting-started/
  ├── jest.config.js
  ├── package.json
  ├── src
  │   └── __tests__
  │       └── homepage.test.ts
  └── yarn.lock

Running our test case.

• In a terminal at the root level of the project, run the following command:

  $ yarn test

• Then you will find a passed result in a terminal as following:

  yarn run v1.22.5
  $ jest
  PASS  src/__tests__/homepage.test.ts (6.782 s)
    Homepage
      √ should launch homepage with expected title (4101 ms)
  Test Suites: 1 passed, 1 total
  Tests:       1 passed, 1 total
  Snapshots:   0 total
  Time:        6.878 s, estimated 7 s
  Ran all test suites.
  Done in 8.15s.

Note

• This code should work cross platforms, Windows, Mac and Linux (of course WSL2).
• I also tested this code on Windows and it worked well for built-in Webkit (Safari) (import { webkit } from 'playwright';) which is bundled with Playwright package.
• If Webkit engine does not work on your computer, please change the code to use chromiume or firefox instead.

Use a React component name as a selector

Normally, we prefer to use CSS selector when getting an element to perform a action. However, for we sometimes use CSS in React component e.g. style-components, emotion libraries. Therefore, out CSS class name is auto-generated and we can't use it as a selector.

We can add data-test-id attribute to our component but we already have why don't we use it. Here are overview of how we use data-test-id and component name selector.

Use data-test-id attribute

• Add data-test-id attribute to React component that we are going to test.
• Use attribute selector [data-test-id="component"] to get a component.
• Use babel-plugin-jsx-remove-data-test-id to remove data-test-id attribute from a production build.
• If we have a tester who is responsible for creating an automated test, it is possible that a developer can forget to add data-test-id attribute.

Use React component name

• Add resq library to a page that we are going to test and use it to query element with React component name.
• cypress-react-selector uses resq under the hood to retrieve HTML nodes.
• Do not need to install any special Webpack plugin.
• A tester can use react-devtools to inspect React component name and use it as a selector.

Code example

• Given, we have React component name like this:

    import { useState } from 'react';
    import { css } from '@emotion/react'
    function App() {
      const [counter, setCounter] = useState(0);
      const handleButtonClick = () => {
        const valueToAdd = 1;
        setCounter(previous => previous + valueToAdd);
      }
      const style = css`
        border: 1px solid #ccc;
      `;
      return (
        <div css={style}>
          <p>
            counter value:  <span>{counter}</span>
          </p>
          <button onClick={handleButtonClick}>Click me</button>
        </div>
      );
    }
    export default App;

• The example of that script to click a button and assert counter value

    import { chromium } from 'playwright';
    import { RESQNode } from 'resq';
    declare global {
      interface Window {
        resq: {
          resq$: (componentName: string, element: HTMLElement) => RESQNode
        }
      }
    }
    // Uppercase name for a test suite
    describe('Page with React component', () => {
      test('should get correct value after click button inside React component', async () => {
        // Arrange
        const browser = await chromium.launch();
        const context = await browser.newContext();
        const page = await context.newPage();
        await page.goto('http://localhost:3000');
        // React Element Selector Query (RESQ) helps us query React components and children by component name or HTML selector.
        // We need to have it on a page that we are going to test.
        // Therefore, we add req script to that page.
        // More info https://github.com/baruchvlz/resq
        await page.addScriptTag({ path: require.resolve('resq') });
        const reactComponentName = 'App';
        const rootElementHandle = await page.waitForSelector('#root');
        const result = await rootElementHandle.evaluateHandle((node: HTMLElement, componentName) => {
          const component = window.resq.resq$(componentName, node);
          return component.node; // div with CSS prop node
        }, reactComponentName);
        const tag = result.asElement();
        const button = await tag.$('button');
        // Actual
        await button.click();
        // Assert
        const counter = await tag.$('span');
        const value = await counter.evaluate(element => element.innerText);
        expect(Number(value)).toBe(1);
        await browser.close();
      });
    });