Skip to content

Latest commit

 

History

History
181 lines (119 loc) · 7.31 KB

Testing Web Components.md

File metadata and controls

181 lines (119 loc) · 7.31 KB
Raw

Testing UI5 Web Components

Note: All examples in this tutorial are taken from the Demo UI5 Web Component (ui5-demo), generated by the package initialization script. For more information on creating a new package with a demo web component inside, click here.

1. Preface

The test framework of choice for UI5 Web Components is WebdriverIO or WDIO for short. It has an easy to use 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 used Web Driver is ChromeDriver

Managing 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

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.

2. Running the tests

2.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 (f.e. 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.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).

2.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.

2.4 Getting the tests to run on Windows

When you first try to run the tests on a Windows machine, you're most likely to get an error saying node-gyp is not installed.

Certain modules, required by the test setup, have a dependency to Node gyp. Normally it is installed along with the other dependencies from NPM, but for a Windows environment specifically, this is not enough, and some manual steps must be performed:

  1. Install Windows build tools:
npm install --global --production windows-build-tools --vs2015

Note the --vs2015 flag.

Also note that this might take some time to complete as several GB might be downloaded in the process.

  1. Configure the right version of Windows build tools for Node.js:
npm config set msvs_version 2015 -–global

  1. Install Python 2.7 if you don't already have it: https://www.python.org/download/releases/2.7/

  2. Set the version of Python to 2.7

npm config set python python2.7

This should be enough to be able to run yarn test successfully. If you still get an error about node-gyp, you should install Windows build tools 2015 (from step 1) manually: https://www.microsoft.com/en-us/download/details.aspx?id=48159 .

3. Writing tests

The simplest test would look something like this:

describe("ui5-demo rendering", () => {
	browser.url("http://localhost:8080/test-resources/pages/index.html");

	it("tests if web component is correctly rendered", () => {
		const innerContent = 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 HTML, value, getProperty, getAttribute, etc...
  • You can modify the DOM with commands such as setProperty, setAttribute etc...

For WDIO capabilities, see:

Note: The standard WDIO configuration we provide automatically synchronizes all test commands' execution with the framework's 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.

4. Debugging tests

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", () => {
    const innerContent = browser.$("#myFirstComponent").shadow$("div");
    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 Chrome Driver, and your test will pause on your breakpoint of choice. Proceed to debug normally.