Skip to main content

Testing

The test framework of choice for UI5 Web Components is WebdriverIO or WDIO for short. It has a straightforward API - https://webdriver.io/docs/api.html, and has excellent support for Web Components.

The browser of choice for test execution is Google Chrome, respectively the WebDriver used is ChromeDriver.

Prerequisites​

Install ChromeDriver​

ChromeDriver is a peer dependency of @ui5/webcomponents-tools. Therefore, you are expected to install and upgrade it manually.

You can install it with npm:

  • npm i --save-dev chromedriver

or with yarn:

  • yarn add -D chromedriver

Note: Google Chrome and ChromeDriver need to be the same version to work together. Whenever you update Google Chrome on your system (or it updates automatically, if allowed), you are expected to also update ChromeDriver to the respective version.

Running the tests​

1. Test configuration​

The configuration for WDIO can be found in the config/ directory under wdio.conf.js.

As explained here in the section about the config/ directory, you can customize, or even completely replace the default configuration.

However, before doing so, please note the following two benefits of working with the default configuration, provided by UI5 Web Components:

  • Hooks, synchronizing the execution of all relevant WDIO commands (e.g. click, url, $, $$) with the rendering of the framework to ensure consistency when reading or changing the state of the components.
  • Additional API methods: setProperty, setAttribute, removeAttribute, hasClass.

So our recommendation would be to modify it, if necessary, but not completely replace it.

2. Running all tests​

npm run test

or

yarn test

This will launch a static server and execute all tests found in the test/specs/ directory of your package.

Note: Before running the tests for the first time, make sure you've built the project, or at least the dev server is running (build or start commands).

3. Running a single test spec​

npm run test test/specs/Demo.spec.js

or

yarn test test/specs/Demo.spec.js

Note: Executing a single test spec only makes sense for debugging purposes, therefore no test server is launched for it. Make sure you're running the start command while running single test specs, as it provides a server and the ability to change files, and test the changes on the fly.

Writing tests​

The simplest test would look something like this:

describe("ui5-demo rendering", async () => {
	await browser.url("test/pages/index.html");

	it("tests if web component is correctly rendered", async () => {
		const innerContent = await browser.$("#myFirstComponent").shadow$("div");
		assert.ok(innerContent, "content rendered");
	});
});

Key points:

  • Load the test page with the browser.url command. You can do this once for each test suite or for each individual test.
  • You can access the web components with $ or $$.
  • You can access the shadow roots with shadow$ or shadow$$.
  • Simulate mouse interaction with the web components by calling the click command on the web component itself or certain parts of its shadow root.
  • Simulate keyboard with the keys command.
  • You can read the DOM with commands such as getHTML, getProperty, getAttribute, etc.
  • You can modify the DOM with commands such as setProperty, setAttribute etc.

For WDIO capabilities, see:

  • Official API: https://webdriver.io/docs/api.html.
  • Additional commands provided in our standard WDIO configuration: setProperty, setAttribute, removeAttribute, hasClass.

Note: The standard WDIO configuration we provide automatically synchronizes all test commands' execution with the framework rendering cycle. Therefore, in the example above, the shadow$ command will internally wait for all rendering to be over before being executed. The same holds true for commands that modify the DOM such as setAttribute or click.

Debugging​

Debugging with WDIO is really simple. Just follow these 3 steps:

  1. Change the WDIO configuration file config/wdio.conf.js to disable headless mode for Google Chrome as follows:

    From:

    module.exports = require("@ui5/webcomponents-tools/components-package/wdio.js");

    to:

    const result = require("@ui5/webcomponents-tools/components-package/wdio.js");
    result.config.capabilities[0]["goog:chromeOptions"].args = ['--disable-gpu']; // From: ['--disable-gpu', '--headless']
    module.exports = result;

    If you happen to debug often, it's recommended to keep the file in this format and just comment out the middle line when you're done debugging.

  2. Set a breakpoint with browser.debug somewhere in your test:

    it("tests if web component is correctly rendered", async () => {
        const innerContent = await browser.$("#myFirstComponent").shadow$("div");
        await browser.debug();
        assert.ok(innerContent, "content rendered");
    });

    For more on debug, see https://webdriver.io/docs/api/browser/debug.html.

  3. Run the single test spec and wait for the browser to open and pause on your breakpoint:

  • Run the dev server, if you haven't already:

    yarn start

    or

    npm run start.

  • Run the single test spec:

    yarn test test/specs/Demo.spec.js

    or

    npm run test test/specs/Demo.spec.js.

Google Chrome will then open in a new window, controlled by WDIO via the ChromeDriver, and your test will pause on your breakpoint of choice. Proceed to debug normally.

Best practices for writing tests​

1. Do not overuse assert.ok​

When an assert.ok fails, the error you get is "Expected something to be true, but it was false". This is fine when you're passing a Boolean, but not ok when there is an expression inside assert.ok and you'd like to know which part of the expression is not as expected.

For example, when assert.ok(a === b, "They match") fails, the error just says that an expression that was expected to be true was false. However, if you use assert.strictEqual(a, b, "They match"), and it fails, the error will say that a was expected to be a certain value, but it was another value, which makes it much easier to debug.

Prefer one of the following, when applicable:

  • assert.notOk(a) instead of assert.ok(!a)
  • assert.strictEqual(a, b) instead of assert.ok(a === b)
  • assert.isBelow(a, b) instead of assert.ok(a < b)
  • assert.isAbove(a, b) instead of assert.ok(a > b)
  • assert.exists / assert.notExists when checking for null or undefined

2. Do not overuse assert.strictEqual​

Use:

  • assert.ok instead of assert.strictEqual(a, true)
  • assert.notOk instead of assert.strictEqual(a, false)

3. Use isExisting to check the DOM​

Preferred:

assert.ok(await browser.$(<SELECTOR>).isExisting())

instead of:

assert.ok((await browser.$$(<SELECTOR>)).length)

4. Do not use browser.executeAsync for properties​

We have custom commands such as getProperty and setProperty to fill in gaps in the WDIO standard command set. Use them instead of manually setting properties with executeAsync.

5. Use assert.include instead of string functions​

Use:

assert.include(text, EXPECTED_TEXT, "Text found")
assert.notInclude(text, NOT_EXPECTED_TEXT, "Text not found")

instead of:

assert.ok(text.indexOf(EXPECTED_TEXT) > -1, "Text found")
assert.ok(text.includes(EXPECTED_TEXT), "Text found")
assert.notOk(text.includes(NOT_EXPECTED_TEXT), "Text not found")

6. Extract variables before asserting​

Avoid complex expressions inside asserts by extracting parts of them to variables and only asserting the variables.