# Hermione > ⚠️ This project has been renamed to [testplane](https://www.npmjs.com/package/testplane), which is backward compatible and you can migrate to it very quickly. More info [here](https://github.com/gemini-testing/testplane/tree/master?tab=readme-ov-file#rename-from-hermione). Hermione is a utility for integration testing of web pages using [WebdriverIO](https://webdriver.io/docs/api) and [Mocha](https://mochajs.org). - [Why you should choose hermione](#why-you-should-choose-hermione) - [Easy to use](#easy-to-use) - [Runs tests in parallel](#runs-tests-in-parallel) - [Runs tests in subprocesses](#runs-tests-in-subprocesses) - [Extensible](#extensible) - [Built-in assert library](#built-in-assert-library) - [Retries failed tests](#retries-failed-tests) - [Executes separate tests](#executes-separate-tests) - [Skips tests in specific browsers](#skips-tests-in-specific-browsers) - [Override browser configuration for test](#override-browser-configuration-for-test) - [`version()`](#versionbrowserversion) - [Offers flexible test configuration](#offers-flexible-test-configuration) - [Automatically initializes and closes grid sessions](#automatically-initializes-and-closes-grid-sessions) - [Fairly waits for screen rotate](#fairly-waits-for-screen-rotate) - [Prerequisites](#prerequisites) - [Selenium-standalone](#selenium-standalone) - [Quick start](#quick-start) - [Using create-hermione-app (a quick way)](#using-create-hermione-app-a-quick-way) - [Configuring .hermione.conf.js by yourself (a slow way)](#configuring-hermioneconfjs-by-yourself-a-slow-way) - [Chrome Devtools Protocol](#chrome-devtools-protocol) - [Webdriver protocol](#webdriver-protocol) - [Commands API](#commands-api) - [Browser commands](#browser-commands) - [clearSession](#clearsession) - [Element commands](#element-commands) - [moveCursorTo](#movecursorto) - [Tests API](#tests-api) - [Arguments](#arguments) - [Hooks](#hooks) - [Skip](#skip) - [Only](#only) - [Config overriding](#config-overriding) - [testTimeout](#testtimeout) - [WebdriverIO extensions](#webdriverio-extensions) - [Sharable meta info](#sharable-meta-info) - [Execution context](#execution-context) - [AssertView](#assertview) - [RunStep](#runstep) - [OpenAndWait](#openandwait) - [Typescript usage](#typescript-usage) - [hermione.ctx typings](#hermionectx-typings) - [.hermione.conf.js](#hermioneconfjs) - [sets](#sets) - [browsers](#browsers) - [desiredCapabilities](#desiredcapabilities) - [gridUrl](#gridurl) - [baseUrl](#baseurl) - [browserWSEndpoint](#browserwsendpoint) - [automationProtocol](#automationprotocol) - [sessionEnvFlags](#sessionenvflags) - [httpTimeout](#httptimeout) - [urlHttpTimeout](#urlhttptimeout) - [pageLoadTimeout](#pageloadtimeout) - [sessionRequestTimeout](#sessionrequesttimeout) - [sessionQuitTimeout](#sessionquittimeout) - [testTimeout](#testtimeout-1) - [waitTimeout](#waittimeout) - [waitInterval](#waitinterval) - [sessionsPerBrowser](#sessionsperbrowser) - [takeScreenshotOnFails](#takescreenshotonfails) - [takeScreenshotOnFailsMode](#takescreenshotonfailsmode) - [takeScreenshotOnFailsTimeout](#takescreenshotonfailstimeout) - [testsPerSession](#testspersession) - [retry](#retry) - [shouldRetry](#shouldretry) - [calibrate](#calibrate) - [meta](#meta) - [windowSize](#windowsize) - [screenshotDelay](#screenshotdelay) - [orientation](#orientation) - [waitOrientationChange](#waitorientationchange) - [resetCursor](#resetcursor) - [tolerance](#tolerance) - [antialiasingTolerance](#antialiasingtolerance) - [compareOpts](#compareopts) - [buildDiffOpts](#builddiffopts) - [assertViewOpts](#assertviewopts) - [openAndWaitOpts](#openandwaitopts) - [screenshotsDir](#screenshotsdir) - [strictTestsOrder](#stricttestsorder) - [compositeImage](#compositeimage) - [screenshotMode](#screenshotmode) - [saveHistoryMode](#savehistorymode) - [agent](#agent) - [headers](#headers) - [transformRequest](#transformrequest) - [transformResponse](#transformresponse) - [strictSSL](#strictssl) - [user](#user) - [key](#key) - [region](#region) - [headless](#headless) - [isolation](#isolation) - [system](#system) - [debug](#debug) - [mochaOpts](#mochaopts) - [expectOpts](#expectopts) - [ctx](#ctx) - [patternsOnReject](#patternsonreject) - [workers](#workers) - [testsPerWorker](#testsperworker) - [parallelLimit](#parallellimit) - [fileExtensions](#fileextensions) - [plugins](#plugins) - [Parallel execution plugin code](#parallel-execution-plugin-code) - [List of useful plugins](#list-of-useful-plugins) - [prepareBrowser](#preparebrowser) - [prepareEnvironment](#prepareenvironment) - [devServer](#devserver) - [CLI](#cli) - [Reporters](#reporters) - [Require modules](#require-modules) - [Overriding settings](#overriding-settings) - [Debug mode](#debug-mode) - [REPL mode](#repl-mode) - [switchToRepl](#switchtorepl) - [Test development in runtime](#test-development-in-runtime) - [How to set up using VSCode](#how-to-set-up-using-vscode) - [How to set up using Webstorm](#how-to-set-up-using-webstorm) - [Environment variables](#environment-variables) - [HERMIONE_SKIP_BROWSERS](#hermione_skip_browsers) - [HERMIONE_SETS](#hermione_sets) - [Programmatic API](#programmatic-api) - [config](#config) - [events](#events) - [errors](#errors) - [CoreError](#coreerror) - [CancelledError](#cancellederror) - [ClientBridgeError](#clientbridgeerror) - [HeightViewportError](#heightviewporterror) - [OffsetViewportError](#offsetviewporterror) - [AssertViewError](#assertviewerror) - [ImageDiffError](#imagedifferror) - [NoRefImageError](#norefimageerror) - [intercept](#intercept) - [run](#run) - [addTestToRun](#addtesttorun) - [readTests](#readtests) - [isFailed](#isfailed) - [isWorker](#isworker) - [halt](#halt) - [Test Collection](#test-collection) - [Test Parser API](#test-parser-api) - [setController(name, methods)](#setcontrollername-methods) ## Why you should choose hermione `Hermione` provides several features that `WebdriverIO` doesn't, and makes the testing process easier. ### Easy to use If you are familiar with [WebdriverIO](http://webdriver.io/) and [Mocha](https://mochajs.org), you can start writing and running tests in 5 minutes! You need to install `hermione` via npm and add a tiny config to your project. For details, see the [Quick start](#quick-start) section. ### Runs tests in parallel When tests are run one by one, it takes a lot of time. `Hermione` can run tests in parallel sessions in different browsers out of the box. ### Runs tests in subprocesses Running of too many tests in parallel can lead to the overloading of the main process CPU usage which causes degradation in test passing time, so Hermione runs all tests in subprocesses in order to solve this problem. ### Extensible `WebdriverIO` provides built-in commands for browser and page manipulation. Often projects need to store some common code and reuse it throughout all tests, so the developer needs to create some helpers and include them in the tests. With `hermione` this is very simple and straightforward. You can add any number of custom commands in the hermione config and use them as `browser.myCustomCommand` in tests. Moreover, `hermione` provides plugins that work like hooks. They allow the developer to prepare the testing environment and react properly to test execution events. ### Built-in assert library when writing integration tests, we need to check for various conditions, such as that a button element has certain attributes. So hermione provides global `expect` variable that gives you access to a number of `matchers` that let you validate different things on the browser, an element or mock object. More about using `expect` and its API you can find [here](https://webdriver.io/docs/api/expect-webdriverio/). ### Retries failed tests Integration tests use a dynamic environment with a lot of dependencies, where any of them could be unstable from time to time. As a result, integration tests turn red randomly, which makes them imprecise. This spoils the entire testing process. To prevent incidental fails, `hermione` retries a failed test before marking it as failed. This makes it possible to get rid of a majority of incidental fails. The number of retries can be specified for all browsers or for a specific browser. :warning: `Hermione` reruns tests in a new browser session to exclude situations when the browser environment is the cause of the failure. ### Executes separate tests Sometimes you only need to run specific tests, not all the tests in a set. `Hermione` makes this possible. You can specify the path to the test file ``` hermione tests/func/mytest.js ``` or filter describes by using the `--grep` option ``` hermione --grep login ``` or simply use the `mocha` `only()` API in the test ```js describe.only('user login', function() {...}); ``` ### Skips tests in specific browsers Sometimes you need to skip a test just in a specific browser, not in all browsers. For example, you don't need to run some test in ~~ugly~~ IE browsers. In `hermione` you can do this with [hermione helper](#skip). For example, you can skip some tests in a specific browser ```js describe('feature', function() { hermione.skip.in('ie8', 'it cannot work in this browser'); it('nowaday functionality', function() {...}); }); ``` or run tests in just one browser ```js describe('feature', function() { // will be skipped in all browsers except Chrome hermione.skip.notIn('chrome', 'it should work only in Chrome'); it('specific functionality', function() {...}); }); ``` In these cases you will see messages in reports with the reason for skipping. To skip a suite or test silently (without any messages in reports), you can pass the third argument with the silent flag: ```js hermione.skip.in('ie8', 'skipReason', {silent: true}); // or hermione.skip.notIn('chrome', 'skipReason', {silent: true}); ``` Or you can use another hermione helper, [only](#only), which is silent by default: ```js hermione.only.in('chrome'); // or hermione.only.notIn('ie8'); ``` `hermione.only.in` will run tests only in the specified browsers and skip the rest silently. `hermione.only.notIn` will run tests in all browsers except the specified ones. ### Override browser configuration for test `Hermione` allows you to override a browser configuration for each test or a whole suite. Each method of `hermione.browser()` provide chaining. #### `version()` ```js // change the browser version for all chindren hermione.browser('chrome').version('70.3'); describe('suite', function() { // ... }); ``` ```js // change the browser version for a specific test hermione.browser('chrome').version('70.3'); it('test', function() {...}); ``` ```js hermione.browser('chrome').version('70.3'); describe('suite', function() { it('test 1', function() {...}); // this call will override the version only for test below hermione.browser('chrome').version('70.1'); it('test 2', function() {...}); }); ``` ### Offers flexible test configuration `Hermione` lets you configure running some set of tests in specific browsers. For example, ```js sets: { desktop: { files: 'tests/desktop', browsers: ['ie8', 'opera'] }, touch: { files: 'tests/touch', browsers: ['iphone', 'android'] } } ``` See [sets](#sets) for more details. ### Automatically initializes and closes grid sessions All work with the grid client is encapsulated in hermione. Forget about `client.init` and `client.end` in your tests ;) ### Fairly waits for screen rotate Request `/session/:sessionId/orientation` is not a part of the official Webdriver specification, so commands `orientation` and `setOrientation` which are provided by client `webdriverio` from the box do not guarantee screen rotate before the next command will start to execute, but `Hermione` solves this problem. ## Prerequisites All you need are browsers that `Hermione` could use for testing. To do this you need to install some browsers, such as [chrome](https://www.google.com/chrome/) (to automate this process you can use the [hermione-headless-chrome](https://github.com/gemini-testing/hermione-headless-chrome) plugin). Next, you have two ways to configure `Hermione` to work with browsers: * Using the devtools protocol (available only for `Chromium`-based browsers). This method does not need to be pre-configured. Just go to the [quick start](#quick-start). * Using the webdriver protocol. In this case you need to set up [Selenium](http://www.seleniumhq.org/) grid. The simplest way to get started is to use one of the NPM selenium standalone packages, such as [vvo/selenium-standalone](https://github.com/vvo/selenium-standalone). For more information about setting up, see [selenium-standalone](#selenium-standalone). ### Selenium-standalone Install `selenium-standalone` by command: ``` npm i -g selenium-standalone ``` Next you need to install browser drivers ``` selenium-standalone install ``` and run your server by executing ``` selenium-standalone start ``` :warning: If you will get error like `No Java runtime present, requesting install.` you should install [Java Development Kit (JDK)](https://www.oracle.com/technetwork/java/javase/downloads/index.html) for your OS. ## Quick start First of all, make sure that all [prerequisites](#prerequisites) are satisfied. Now you have two ways to configure project. ### Using create-hermione-app (a quick way) You just need to run the cli command from [create-hermione-app](https://github.com/gemini-testing/create-hermione-app) tool and answer a few questions: ``` npm init hermione-app YOUR_PROJECT_PATH ``` To skip all questions just add the option `-y` at the end. ### Configuring .hermione.conf.js by yourself (a slow way) Create hermione config file with name `.hermione.conf.js` in the project root. There are two configuration options depending on the method selected in the `prerequisites` section. #### Chrome Devtools Protocol ```javascript module.exports = { sets: { desktop: { files: 'tests/desktop/**/*.hermione.js' } }, browsers: { chrome: { automationProtocol: 'devtools', desiredCapabilities: { browserName: 'chrome' } } } }; ``` #### Webdriver protocol ```javascript module.exports = { gridUrl: 'http://localhost:4444/wd/hub', sets: { desktop: { files: 'tests/desktop/*.hermione.js' } }, browsers: { chrome: { automationProtocol: 'webdriver', // default value desiredCapabilities: { browserName: 'chrome' } } } }; ``` Write your first test in `tests/desktop/github.hermione.js` file. ```javascript describe('github', function() { it('should check repository name', async ({ browser }) => { await browser.url('https://github.com/gemini-testing/hermione'); await expect(browser.$('#readme h1')).toHaveText('Hermione'); }); }); ``` Finally, run tests (be sure that you have already run `selenium-standalone start` command in next tab). ``` node_modules/.bin/hermione ``` ## Commands API Since Hermione is based on [WebdriverIO v8](https://webdriver.io/docs/api/), all the commands provided by WebdriverIO are available in it. But Hermione also has her own commands. ### Browser commands #### clearSession Browser command that clears session state (deletes cookies, clears local and session storages). For example: ```js it('test', async ({ browser }) => { await browser.url('https://github.com/gemini-testing/hermione'); (await browser.getCookies()).length; // 5 await browser.execute(() => localStorage.length); // 2 await browser.execute(() => sessionStorage.length); // 1 await browser.clearSession(); (await browser.getCookies()).length; // 0 await browser.execute(() => localStorage.length); // 0 await browser.execute(() => sessionStorage.length); // 0 }); ``` ### Element commands #### moveCursorTo > This command is temporary and will be removed in the next major (hermione@9). Differs from the standard [moveTo](https://webdriver.io/docs/api/element/moveTo/) in that it moves the cursor relative to the top-left corner of the element (like it was in hermione@7). Move the mouse by an offset of the specified element. If offset is not specified then mouse will be moved to the top-left corder of the element. Usage: ```typescript await browser.$(selector).moveCursorTo({ xOffset, yOffset }); ``` Available parameters: * **xOffset** (optional) `Number` – X offset to move to, relative to the top-left corner of the element; * **yOffset** (optional) `Number` – Y offset to move to, relative to the top-left corner of the element. ## Tests API ### Arguments Hermione calls test and hook callback with one argument. This argument is an object with the next properties: - **browser** - browser client - **currentTest** - current executing test Example: ```js beforeEach(async ({ browser, currentTest }) => { await browser.url(`/foo/bar?baz=${currentTest.id}`); }); afterEach(async ({ browser, currentTest }) => { // Do some post actions with browser }); it('some test', async ({ browser, currentTest }) => { await browser.click('.some-button'); // Do some actions and asserts }); ``` You also can pass any data into your test through parameters: ```js beforeEach(async (opts) => { opts.bar = 'bar'; }); it('some test', async ({ browser, bar }) => { await browser.url(`/foo/${bar}`); // Do some actions and asserts }); ``` **browser** and **currentTest** also available through callback context: ```js beforeEach(async function() { await this.browser.url(`/foo/bar?baz=${this.currentTest.id}`); }); afterEach(async function() { // Do some post actions with this.browser }); it('some test', async function() { await this.browser.click('.some-button'); // Do some actions and asserts }); ``` ### Hooks `before` and `after` hooks **are forbidden** in `hermione`, you should use `beforeEach` and `afterEach` hooks instead. This feature was implemented in order to ensure better stability while running tests and make them independent of each other. ### Skip This feature allows you to ignore the specified suite or test in any browser, with an additional comment. You can do this by using the global `hermione.skip` helper. It supports the following methods: - `.in` – Adds matchers for browsers with the additional comment. - `.notIn` – `.in` method with the reverted value. Each of these methods takes the following arguments: - browser {String|RegExp|Array} – Matcher for browser(s) to skip. - [comment] {String} – Comment for skipped test. - [options] {Object} – Additional options. **Note that matchers will be compared with `browserId` specified in the config file, e.g. `chrome-desktop`.** For example, ```js describe('feature', function() { hermione.skip.in('chrome', "It shouldn't work this way in Chrome"); it('should work this way', function() { return runTestThisWay(); }); it('should work that way', function() { return runTestThatWay(); }); hermione.skip.in(['chrome', 'firefox', /ie\d*/], 'Unstable test, see ticket TEST-487'); it('should have done some tricky things', function() { return runTrickyTest(); }); }); ``` In this case, the behaviour `it should work this way` will be skipped only in `chrome` browser, but will be run in other browsers. `It should work that way` will not be ignored. So only the nearest test will be skipped. If you need to skip all tests within a suite, you can apply the `skip` helper to a `describe` so all tests within this suite will be skipped with the same comment. ```js hermione.skip.in('chrome', 'skip comment'); describe('some feature', function() { it(...); it(...); }); ``` You can also use the `.notIn` method to invert matching. For example, ```js // ... hermione.skip.notIn('chrome', 'some comment'); it('should work this way', function() { return doSomething(); }); // ... ``` In this case, the test will be skipped in all browsers except `chrome`. All of these methods are chainable, so you can skip a test in several browsers with different comments. For example, ```js // ... hermione.skip .in('chrome', 'some comment') .notIn('ie9', 'another comment'); it('test1', function() { return doSomething(); }); // ... ``` If you need to skip a test in all browsers without a comment, you can use [mocha `.skip` method](http://mochajs.org/#inclusive-tests) instead of `hermione.skip.in(/.*/);`. The result will be the same. ### Only This feature allows you to ignore the specified suite or test in any browser silently (without any messages in reports). You can do this by using the global `hermione.only` helper. It supports two methods: - `.in` — The `hermione.skip.notIn` method with the silent flag, - `.notIn` — The `hermione.skip.in` with the silent flag. These methods take the following arguments: - browser {String|RegExp|Array} — A matcher for browser(s) to skip. For example: ```js // ... hermione.only.in('chrome'); it('should work this way', function() { return doSomething(); }); ``` The test will be skipped all browsers **silently** except in `chrome`. ```js hermione.only.notIn('ie9'); it('should work another way', function() { return doSomething(); }); ``` The test will be processed in all browsers and **silently** skipped in `ie9`. ### Config overriding You can override some config settings for specific test, suite or hook via `hermione.config.*` notation. #### testTimeout Overrides [testTimeout](#testtimeout-1) config setting. Can be set for tests and suites. ```js hermione.config.testTimeout(100500); it('some test', function() { return doSomething(); }); ``` ### WebdriverIO extensions `Hermione` adds some useful methods and properties to the `webdriverio` session after its initialization. #### Sharable meta info Implemented via two commands: * setMeta(key, value) * getMeta([key]) These methods allow you to store some information between webdriver calls and it can then be used in custom commands, for instance. This meta information will be shown in the [html-reporter](https://github.com/gemini-testing/html-reporter). **Note**: hermione saves the last URL opened in the browser in meta info. Example: ```js it('test1', async ({ browser }) => { await browser.setMeta('foo', 'bar'); await browser.url('/foo/bar?baz=qux'); const val = await browser.getMeta('foo'); console.log(val); // prints 'bar' const url = await browser.getMeta('url'); console.log(url); // prints '/foo/bar?baz=qux' const meta = await browser.getMeta(); console.log(meta); // prints `{foo: 'bar', url: '/foo/bar?baz=qux'}` }); ``` #### Execution context The execution context can be accessed by the `browser.executionContext` property, which contains the current test/hook object extended with the browser id. Example: ```js it('some test', async ({ browser }) => { await browser.url('/foo/bar'); console.log('test', browser.executionContext); }); ``` will print something like this ``` test: { "title": "some test", "async": 0, "sync": true, "timedOut": false, "pending": false, "type": "test", "body": "...", "file": "/foo/bar/baz/qux.js", "parent": "#", "ctx": "#", "browserId": "chrome", "meta": {}, "timer": {} } ``` ### AssertView Command that adds ability to take screenshot for test state. Each state should have his own unique name. For example: ```js it('some test', async ({ browser }) => { await browser.url('some/url'); await browser.assertView('plain', '.button'); await browser.click('.button'); await browser.assertView('clicked', '.button'); }); ``` Could also be used as element's method: ```js it('some test', async ({ browser }) => { await browser.url('some/url'); const elem = await browser.$('.button'); await elem.assertView('plain'); await elem.click(); await elem.assertView('clicked'); }); ``` *Note: assertView will trigger [waitForExist](https://webdriver.io/docs/api/element/waitForExist/) with [waitTimeout](#waittimeout) and [waitInterval](#waitinterval)* Parameters: - state (required) `String` – state name; should be unique within one test - selector (required) `String|String[]` – DOM-node selector that you need to capture - opts (optional) `Object`: - ignoreElements (optional) `String|String[]` – elements, matching specified selectors will be ignored when comparing images - tolerance (optional) `Number` – overrides config [browsers](#browsers).[tolerance](#tolerance) value - antialiasingTolerance (optional) `Number` – overrides config [browsers](#browsers).[antialiasingTolerance](#antialiasingTolerance) value - ignoreDiffPixelCount (optional) `Number | string` - the maximum amount of different pixels to still consider screenshots "the same". For example, when set to 5, it means that if there are 5 or fewer different pixels between two screenshots, they will still be considered the same. Alternatively, you can also define the maximum difference as a percentage (for example, 3%) of the image size. This option is useful when you encounter a few pixels difference that cannot be eliminated using the tolerance and antialiasingTolerance settings. The default value is 0. - allowViewportOverflow (optional) `Boolean` – by default Hermione throws an error if element is outside the viewport bounds. This option disables check that element is outside of the viewport left, top, right or bottom bounds. And in this case if browser option [compositeImage](#compositeimage) set to `false`, then only visible part of the element will be captured. But if [compositeImage](#compositeimage) set to `true` (default), then in the resulting screenshot will appear the whole element with not visible parts outside of the bottom bounds of viewport. - captureElementFromTop (optional) `Boolean` - ability to set capture element from the top area or from current position. In the first case viewport will be scrolled to the top of the element. Default value is `true` - compositeImage (optional) `Boolean` - overrides config [browsers](#browsers).[compositeImage](#compositeImage) value - screenshotDelay (optional) `Number` - overrides config [browsers](#browsers).[screenshotDelay](#screenshotDelay) value - selectorToScroll (optional) `String` - DOM-node selector which should be scroll when the captured element does not completely fit on the screen. Useful when you capture the modal (popup). In this case a duplicate of the modal appears on the screenshot. That happens because we scroll the page using `window` selector, which scroll only the background of the modal, and the modal itself remains in place. Works only when `compositeImage` is `true`. - disableAnimation (optional): `Boolean` - ability to disable animations and transitions while capturing a screenshot. All options inside `assertView` command override the same options in the [browsers](#browsers).[assertViewOpts](#assertViewOpts). Full example: ```js it('some test', async ({ browser }) => { await browser.url('some/url'); await browser.assertView( 'plain', '.form', { ignoreElements: ['.link'], tolerance: 5, antialiasingTolerance: 4, allowViewportOverflow: true, captureElementFromTop: true, compositeImage: true, screenshotDelay: 10, selectorToScroll: '.modal' } ); }); ``` For tests which have been just written using `assertView` command you need to update reference images, so for the first time `hermione` should be run with option `--update-refs` or via command `gui` which is provided by plugin [html-reporter](https://github.com/gemini-testing/html-reporter) (we highly recommend to use `gui` command instead of option `--update-refs`). ### RunStep Command that allows to add human-readable description for commands in `history`, when it is enabled ([html-reporter](https://github.com/gemini-testing/html-reporter) required) with [saveHistoryMode](#savehistorymode). For example: ```js it('some test', async ({browser}) => { await browser.runStep('some step name', async () => { await browser.url('some/url'); await browser.$('some-selector').click(); }); await browser.runStep('other step name', async () => { await browser.runStep('some nested step', async () => { await browser.$('not-exist').click(); }); }); await browser.runStep('another step', async () => { ... }); }); ``` Will produce the following history, if test fails on 'Can't call click on element with selector "not-exist" because element wasn't found': - hermione: init browser - some step name - other step name - some nested step - $("not-exist") - click() - waitForExist In this example step `some step name` is collapsed, because it is completed successfully. You can also return values from step: ```js const parsedPage = await browser.runStep('parse page', async () => { ... return someData; }); ``` Parameters: - stepName (required) `String` – step name - stepCb (required) `Function` – step callback *Note: [html-reporter](https://github.com/gemini-testing/html-reporter) v9.7.7+ provides better history representation.* ### OpenAndWait Command that allows to open page and wait until it loads (by combination of the specified factors). For example: ```js it('some test', async ({browser}) => { await browser.openAndWait('some/url', { selector: ['.some', '.selector'], predicate: () => document.isReady, ignoreNetworkErrorsPatterns: ['https://mc.yandex.ru'], waitNetworkIdle: true, waitNetworkIdleTimeout: 500, failOnNetworkError: true, timeout: 20000, }); }); ``` In this example, page will be considered as loaded, if elements with selectors `.some` and `.selector` exists, `document.isReady` is `true`, it has been 500 ms since the last network request succeeded, and there were no errors, while trying to load images, fonts and stylesheets. Parameters: - url (required) `String` – page url - waitOpts (optional) `Object`: - selector (optional) `String|String[]` – Selector(s) to element(s), which should exist on the page. - predicate (optional) `() => Promise | bool` – Predicate, which should return `true` if page is loaded. Predicate is being executed in the browser context: [waitUntil](https://webdriver.io/docs/api/element/waitUntil). - waitNetworkIdle (optional) `Boolean` – Waits until all network requests are done. `true` by default. Only works in chrome browser or when using [Chrome Devtools Protocol](#chrome-devtools-protocol). - waitNetworkIdleTimeout (optional) `Number` - Time (ms) after all network requests are resolved to consider network idle. 500 by default. - failOnNetworkError (optional) `Boolean` – If `true`, throws an error when network requests are failed. `true` by default. Only works in chrome browser or when using [Chrome Devtools Protocol](#chrome-devtools-protocol). - shouldThrowError (optional) `(match) => Boolean` - Predicate, which should return `true` on [Match](https://webdriver.io/docs/api/mock#match), if network error is considered critical for page load. By default, throws an error on image, stylesheet and font load error. - ignoreNetworkErrorsPatterns (optional) `Array` - Array of url patterns to ignore network requests errors. Has a priority over `shouldThrowError` - timeout (optional) `Number` - Page load timeout. [pageLoadTimeout](#pageloadtimeout) by default. Throws an error, if selectors are still not exist after timeout, or predicate is still resolving false. ## Typescript usage To write hermione tests on typescript, you would need to install `ts-node`: ```bash npm i -D ts-node ``` And include hermione types in your `tsconfig.json` file: ```js // tsconfig.json { // other tsconfig options "compilerOptions": { // other compiler options "types": [ // other types "hermione", ] } } ``` Now you will be able to write hermione tests using typescript. ### hermione.ctx typings If you want to extend hermione.ctx typings, you could use module augmentation: ```ts import type { HermioneCtx } from "hermione"; declare module "hermione" { interface HermioneCtx { someVariable: string; } } ``` Now `hermione.ctx` will have `someVariable` typings ## .hermione.conf.js `hermione` is tuned using a configuration file. By default, it uses `.hermione.conf.js`, but you can use the `--config` option to specify a path to the configuration file. There is only one required field – `browsers`. ```javascript module.exports = { browsers: { chrome: { desiredCapabilities: { browserName: 'chrome' } } } }; ``` ### sets You can use sets to bind some set of tests to certain browsers. Format of the sets section: ```javascript sets: { common: { // run tests associated with this path in all browsers files: 'tests/common' // which are configured in the `browsers` option }, desktop: { files: [ 'tests/desktop/*.hermione.js', 'tests/common/*.hermione.js' ], ignoreFiles: ['tests/desktop/fixtures/**'], // exclude directories from reading while test finding browsers: ['browser'] // run tests which match the specified masks in the browser with the `browser` id } } ``` * `files` – A list of test files or directories with test files. This can be a string if you want to specify just one file or directory. Also, you can use masks for this property. * `ignoreFiles` - A list of paths or masks to ignore from reading while test finding. When you write `!**/some-dir/**` it means that the directory will be read, but all the entries will not be included in the results. So using `ignoreFiles` you can speed up test reading for your project. * `browsers` – A list of browser IDs to run the tests specified in `files`. All browsers by default. You can specify sets to run using the CLI option `--set`. If sets are not specified in the config and paths were not passed from CLI, all files from the `hermione` directory are launched in all browsers specified in the config. Running tests using sets: ``` hermione --set desktop ``` ### browsers **Required.** The list of browsers to use for running tests. The browser section has the following format ```javascript browsers: { : {