Skip to main content

How to Upgrade hermione to Version 8.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";
  • "How to Upgrade hermione to Version 6.x";
  • "How to Upgrade hermione to Version 7.x".

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

What Has Changed?​

Major Changes​

Package Exports Changed​

To use hermione via API in JavaScript, you now need to import hermione as follows:

const { default: hermione } = require("hermione");

Previously, you could write it like this:

const hermione = require("hermione");

For TypeScript:

import hermione from "hermione";

moveTo Command Changed​

The moveTo command now moves the cursor relative to the center of the element rather than the top-left corner. If the element is not visible, it will scroll to it. Previously, calling the command without arguments (await browser.$('body').moveTo()) moved the cursor to the top-left corner of the element - now it will move to the center of the element.

If you don't have time to switch to the new logic of moveTo, you can use the moveCursorTo command, which works as it did in hermione@7. This command was added in hermione@8.1.0. The moveCursorTo command is temporary and will be removed in the next major version.

Dropped Support for Node.JS < 18.x​

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

Minor Changes​

  • Added REPL mode for step-by-step debugging of tests in all browsers (not only CDP) without restarting.

  • Added a browser command clearSession to clear session state:

    • Deletes cookies;
    • Clears local storage;
    • Clears session storage.

  • Added a browser command openAndWait with customizable wait options for page loads (by selector, custom predicate, network request, etc.).

  • Added a CLI option --devtools to simplify switching between the two protocols (devtools and webdriver).

  • Improved stack trace for unhandled rejection errors.

  • Now isolation is enabled by default for Chrome >= 94.

  • During the execution of the assertView command, CSS animations on the page will be disabled by default.

  • Implemented generation of a unique X-Request-ID header for each request in the browser. The header consists of ${TEST_X_REQ_ID}${DELIMITER}$BROWSER_X_REQ_ID}, where:

    • TEST_X_REQ_ID - a unique UUID for each test run (including retries of the same test). This allows you to find all requests related to a single test run in the logs.
    • DELIMITER - __ separator between the test and request UUIDs.
    • BROWSER_X_REQ_ID - a unique UUID for each browser request.

    A real example of a UUID is 2f31ffb7-369d-41f4-bbb8-77744615d2eb__e8d011d8-bb76-42b9-b80e-02f03b8d6fe1.

Patch Changes​

  • Fixed disabling animations in iframes for iOS when using assertView.
  • Eliminated reinitialization of browser sessions in workers.
  • Fixed a bug where it was impossible to disable isolation.

How to Migrate?​

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

2. If Using hermione via API in JavaScript, Switch to TypeScript or Change the Import Statement​

3. If Using moveTo, Switch to moveToCursor or Specify Coordinates from the Center of the Element​

Support​

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