Skip to main content

How to Upgrade hermione to Version 7.x

warning

If your project is using a hermione version earlier than 4.x, first read "How to Upgrade hermione to Version 4.x," "How to Upgrade hermione to Version 5.x," and "How to Upgrade hermione to Version 6.x."

We recommend upgrading hermione in stages, ensuring each step that all project tests run correctly.

What Has Changed?​

Major Changes​

Dropped Support for Node.JS < 16.x​

In this major version, hermione no longer supports versions Node.JS < 16.x.

Handling Unhandled Rejections​

When an Unhandled rejection error occurs in the master or workers, hermione now performs a graceful shutdown. This means all subsequent tests in the queue will end with the error Browser request was cancelled, and hermione itself will terminate with exit code 1.

This change is necessary to protect users from writing incorrect tests. Example of a test with an error:

it("test", async ({ browser }) => {
    await browser.url("https://yandex.ru/search/?text=aaa");
    expect(browser).toHaveUrlContaining("foo-bar-baz");
});

A keen observer will notice that I forgot to add await before calling expect. In this case, the test will immediately pass after navigating to the URL. Only then will an Unhandled rejection error appear, which hermione@6 would swallow. But hermione@7 will catch and immediately terminate the test run. Unfortunately, it is impossible to determine from which test the Unhandled rejection error originated. For example, a test could be written like this:

it("test2", async () => {
    new Promise((resolve, reject) => {
        setTimeout(() => {
            reject("Something goes wrong");
        }, 30000);
    });
});

This test will immediately pass, and only after 30 seconds (assuming there are still tests in the queue to run) will an Unhandled rejection error appear.

Therefore, to find the problematic test, you will need to look at the execution log and find the last completed tests before the error information. The error will look something like this:

[13:48:57 GMT+3] Unhandled Rejection in hermione:worker:10830:
Promise: {}
Reason: Something goes wrong
[13:48:57 GMT+3] Terminating on critical error: Unhandled Rejection in hermione:worker:10830:
Promise: {}
Reason: Something goes wrong

test.id and suite.id Are Now Properties​

The id for a test and suite is now a property, not a method, and should be used as test.id or suite.id. The test.id call is usually used in the hermione config to define the screenshotsDir option.

Removed the saveHistory Option from the Config​

The saveHistory option has been removed from the config. You now need to use saveHistoryMode with available values: all, none, onlyFailed. The default is all, meaning history is saved for all tests. So, you can skip explicitly setting this option.

Minor Changes​

  • Upgraded from webdriverio@7 to webdriverio@8;

  • Increased test reading speed by about 3 times: tests are now read once in the master (previously read separately for each browser);

  • Added the ability to write the config in TS. You can create .hermione.conf.ts, and hermione will compile and read it (assuming your project includes ts-node);

  • Added timestamps to hermione logs, looking like:

    [13:48:09 GMT+3] ✓ suite test2 [chrome-desktop:SESSION_ID] - 875ms

Patch Changes​

  • Properly supported taking screenshots on devices with fractional pixelRatio (e.g., Google Pixel). Previously, screenshots on such devices were incorrect;
  • Moving the cursor away using the resetCursor: true option no longer triggers an error if the top-left corner of the body element has negative coordinates.

How to Migrate?​

1. Update hermione to 7+ and Plugins to the Latest Versions​

Specifically:

If you are not using any of these plugins, you do not need to install them.

2. Replace test.id() with test.id in the hermione Config​

If you are not using test.id(), there is nothing to do.

3. Replace the saveHistory Option with saveHistoryMode in the hermione Config​

If you are not using saveHistory, there is nothing to do.

4. Replace the Usage of a Custom Mocha Interface​

If you are using a custom mocha interface, replace it with the mocha interface from hermione dependencies:

- const baseBdd = require('@gemini-testing/mocha/lib/interfaces/bdd');

+ const { dependencies: hermioneDeps } = require('hermione/package');
+ const mochaModule = '@gemini-testing/mocha' in hermioneDeps ? '@gemini-testing/mocha' : 'mocha';
+ const { interfaces: { bdd: baseBdd } } = require(mochaModule);

Support​

If you encounter issues during the migration to the new version or have any questions, visit github issues — we will definitely help you!