From 1a576f224bea964844939f8df1b09d1ad4c51403 Mon Sep 17 00:00:00 2001
From: Julien Mougenot <jum@odoo.com>
Date: Fri, 1 Mar 2024 16:51:25 +0000
Subject: [PATCH 1/2] [IMP] web: HOOT - documentation

X-original-commit: eb756332c9b7a6b8effb56e091d5766f0b01769b
---
 content/developer/reference/frontend.rst      |    1 +
 .../reference/frontend/unit_testing.rst       |   90 +
 .../reference/frontend/unit_testing/hoot.rst  | 1662 +++++++++++++++++
 .../frontend/unit_testing/mock_server.rst     |  383 ++++
 .../frontend/unit_testing/web_helpers.rst     |  187 ++
 5 files changed, 2323 insertions(+)
 create mode 100644 content/developer/reference/frontend/unit_testing.rst
 create mode 100644 content/developer/reference/frontend/unit_testing/hoot.rst
 create mode 100644 content/developer/reference/frontend/unit_testing/mock_server.rst
 create mode 100644 content/developer/reference/frontend/unit_testing/web_helpers.rst

diff --git a/content/developer/reference/frontend.rst b/content/developer/reference/frontend.rst
index e2b7fae340..698fd26dc8 100644
--- a/content/developer/reference/frontend.rst
+++ b/content/developer/reference/frontend.rst
@@ -21,3 +21,4 @@ Web framework
    frontend/mobile
    frontend/qweb
    frontend/odoo_editor
+   frontend/unit_testing
diff --git a/content/developer/reference/frontend/unit_testing.rst b/content/developer/reference/frontend/unit_testing.rst
new file mode 100644
index 0000000000..957cb114d1
--- /dev/null
+++ b/content/developer/reference/frontend/unit_testing.rst
@@ -0,0 +1,90 @@
+:show-content:
+:show-toc:
+
+=======================
+JavaScript Unit Testing
+=======================
+
+Writing unit tests is as important as writing the code itself: it helps to
+ensure that the code is written according to a given specification and that it
+remains correct as it evolves.
+
+Testing Framework
+=================
+
+Testing the code starts with a testing framework. The framework provides a level
+of abstraction that makes it possible to write tests in an easy and efficient way.
+It also provides a set of tools to run the tests, make assertions and report the
+results.
+
+Odoo developers use a home-grown testing framework called :abbr:`HOOT (Hierarchically Organized
+Odoo Tests)`. The main reason for using a custom framework is that it allows us to extend it based
+on our needs (tags system, mocking of global objects, etc.).
+
+On top of that framework we have built a set of tools to help us write tests for the web client
+(`web_test_helpers`), and a mock server to simulate the server side (`mock_server`).
+
+You can find links to the reference of each of these parts below, as well as a section filled with
+examples and best practices for writing tests.
+
+Setup
+=====
+
+Before learning how to write tests, it is good to start with the basics. The following steps
+will ensure that your test files are properly picked up by the test runner.
+
+Note that in existing addons, most of these steps can be skipped since the proper
+folder structure and asset bundles are probably set up.
+
+#. Writing files in the right **place**:
+
+    All JavaScript test files should be put under the `/static/tests` folder of the
+    related addon (e.g. :file:`/web/static/tests/env.test.js`).
+
+#. Using the right **name**:
+
+    Test files must end with :file:`.test.js`. This is not only a convention, but a requirement
+    for test files to be picked up by the runner. All other JavaScript files will be
+    interpreted either as production code (i.e. the code to be tested), or as test
+    helper files (such as `web_test_helpers <{GITHUB_PATH}/addons/web/static/tests/web_test_helpers.js>`_).
+
+    .. note::
+        It is to be noted that there is an exception for :file:`.hoot.js` files, which are not
+        considered as test files, but as global modules for the whole test run, while other
+        JavaScript modules are re-created for each test suite. Since the same instance of
+        these modules will be running for the whole test run, they follow strict constraints,
+        such as restricted imports, or advanced memory management techniques to
+        ensure no side-effects are affecting tests.
+
+#. Calling the files in the right **bundle**:
+
+    Test files, added in the right folder, must be included in the `web.assets_unit_tests`
+    bundle. For ease of use, this can be done with glob syntax to import all test
+    and test helper files:
+
+    .. code:: python
+
+        # Unit test files
+        'web.assets_unit_tests': [
+            'my_addon/static/tests/**/*',
+        ],
+
+#. Heading to the right **URL**:
+
+    To run tests, you can then go to the `/web/tests` URL.
+
+    .. tip::
+        This page can be accessed through :icon:`fa-bug` :menuselection:`Debug menu --> Run Unit Tests`.
+
+Writing tests
+=============
+
+After creating and including test files, it is time to write tests. You may refer
+to the following documentation sections to learn about the testing framework.
+
+.. toctree::
+    :titlesonly:
+
+    unit_testing/hoot
+    unit_testing/web_helpers
+    unit_testing/mock_server
diff --git a/content/developer/reference/frontend/unit_testing/hoot.rst b/content/developer/reference/frontend/unit_testing/hoot.rst
new file mode 100644
index 0000000000..beb53450c0
--- /dev/null
+++ b/content/developer/reference/frontend/unit_testing/hoot.rst
@@ -0,0 +1,1662 @@
+====
+HOOT
+====
+
+Overview
+========
+
+:abbr:`HOOT (Hierarchically Organized Odoo Tests)` is a testing framework written with Owl whose
+key features are:
+
+- to register and run tests and test suites;
+- to display an intuitive interface to view and filter test results;
+- to provide ways to interact with the DOM to simulate user actions;
+- to provide low-level helpers allowing to mock various global objects.
+
+As such, it has been integrated as a :file:`lib/` in the Odoo codebase and exports 2 main modules:
+
+- :file:`@odoo/hoot-dom`: (can be used in production code) helpers to:
+
+    - **interact** with the DOM, such as :js:meth:`click` and :js:meth:`press`;
+    - **query** elements from the DOM, such as :js:meth:`queryAll` and :js:meth:`waitFor`;
+
+- :file:`@odoo/hoot`: (only to be used in tests) all the test framework features:
+
+    - `test`, `describe` and `expect`
+    - test hooks like `after` and `afterEach`
+    - fixture handling with `getFixture`
+    - date and time handling like `mockDate` or `advanceTime`
+    - mocking network responses through :js:meth:`mockFetch` or :js:meth:`mockWebSocket`
+    - every helper exported by :file:`@odoo/hoot-dom`
+
+.. note::
+    This section of the documentation is not meant to list *all* helpers available
+    in Hoot (the full list can be found in the `@odoo/hoot <{GITHUB_PATH}/addons/web/static/lib/hoot/hoot.js>`_
+    module itself). The goal here is to showcase the most used helpers and to justify
+    some of the decisions that have led to the current shape of the testing framework.
+
+Running tests
+=============
+
+In Odoo, frontend unit tests can be run by going to the `/web/tests` URL. Most of
+the setup for calling the test runner is already in place:
+
+- the `web.assets_unit_tests` bundle is already defined, and picks up all tests
+  defined in most addons;
+
+- a :file:`start.hoot.js` file takes care of calling the test runner with its exported
+  `start` entry point function.
+
+When going to the test page, tests will be run sequentially and the results will
+be displayed in the console and in the GUI (if not running in `headless` mode).
+
+Runner options
+--------------
+
+The runner can be configured either:
+
+- through the interface (with the configuration dropdown and the search bar);
+- or through the URL query parameters (e.g. `?headless` to run in headless mode).
+
+Here is the list of available options for the runner:
+
+- `bail`
+    Amount of failed tests after which the test runner will be stopped. A falsy value
+    (including 0) means that the runner should never be aborted. (default: `0`)
+
+- `debugTest`
+    Same as the `FILTER_SCHEMA.test` filter, while also putting the test runner in
+    "debug" mode. See `TestRunner.debug` for more info. (default: `false`)
+
+- `fps`
+    Sets the value of frames per seconds (this will be transformed to milliseconds and used in
+    `advanceFrame`)
+
+- `filter`
+    Search string that will filter matching tests/suites, based on their full name (including
+    their parent suite(s)) and their tags. (default: `""`)
+
+- `frameRate`
+    *Estimated* amount of frames rendered per second, used when mocking animation frames. (default:
+    `60` fps)
+
+- `fun`
+    Lightens the mood. (default: `false`)
+
+- `headless`
+    Whether to render the test runner user interface. (default: `false`)
+
+- `id`
+    IDs of the suites OR tests to run exclusively. The ID of a job is generated
+    deterministically based on its full name.
+
+- `loglevel`
+    Log level used by the test runner. The higher the level, the more logs will be displayed:
+
+    - `0`: only runner logs are displayed (default)
+    - `1`: all suite results are also logged
+    - `2`: all test results are also logged
+    - `3`: debug information for each test is also logged
+
+- `manual`
+    Whether the test runner must be manually started after page load (defaults to starting
+    automatically). (default: `false`)
+
+- `notrycatch`
+    Removes the safety of `try .. catch` statements around each test's run function to let errors
+    bubble to the browser. (default: `false`)
+
+- `order`
+    Determines the order of test execution:
+
+    - `"fifo"`: tests will be run sequentially as declared in the file system;
+    - `"lifo"`: tests will be run sequentially in the reverse order;
+    - `"random"`: shuffles tests and suites within their parent suite.
+
+- `preset`
+    Environment in which the test runner is running. This parameter is used to
+    determine the default value of other features, namely:
+
+    - the user agent;
+    - touch support;
+    - expected size of the viewport.
+
+- `showdetail`
+    Determines how the failed tests must be unfolded in the UI. (default: `"first-fail"`)
+
+- `tag`
+    Tag names of tests and suites to run exclusively (case insensitive). (default: empty)
+
+- `timeout`
+    Duration (in milliseconds) at the end of which a test will automatically fail.
+    (default: `5` seconds)
+
+.. note::
+    When selecting tests and suites to run, an implicit `OR` is applied between
+    the *including* filters. This means that adding more inclusive filters will
+    result in more tests being run. This applies to the `filter`, `id` and `tag`
+    filters (*excluding* filters however will remove matching tests from the list
+    of tests to run).
+
+
+Writing tests
+=============
+
+Test
+----
+
+Writing a test can be very straightforward, as it is just a matter of calling the `test` function
+with a name and a function that will contain the test logic.
+
+Here is a simple example:
+
+.. code-block:: javascript
+
+    import { expect, test } from "@odoo/hoot";
+
+    test("My first test", () => {
+        expect(2 + 2).toBe(4);
+    });
+
+
+Describe
+--------
+
+Most of the time, tests are not that simple. They often require some setup and teardown,
+and sometimes they need to be grouped together in a suite. This is where the `describe`
+function comes into play.
+
+Here is how you would declare a suite and a test within it:
+
+.. code-block:: javascript
+
+    import { describe, expect, test } from "@odoo/hoot";
+
+    describe("My first suite", () => {
+        test("My first test", () => {
+            expect(2 + 2).toBe(4);
+        });
+    });
+
+.. important::
+    In Odoo, all test files are run in an isolated environment and are wrapped within a global
+    `describe` block (with the name of the suite being the *path* of the test file).
+
+    With that in
+    mind you should not need to declare a suite in your test files, although you can still declare
+    sub-suites in the same file if you still want to split the file's suite, for organization
+    or tagging purposes.
+
+
+Expect
+======
+
+The `expect` function is the main assertion function of the framework. It is used
+to assert that a value or an object is what it is expected to be or in the state
+it is supposed to be. To do so, it provides a few modifiers and a wide range of
+matchers.
+
+
+Modifiers
+---------
+
+An `expect` modifier is a getter that returns another set of *altered* matchers that will behave in
+a specific way.
+
+- `not`
+    Inverts the result of the following matcher: it will succeed if the matcher fails.
+
+    .. code-block:: javascript
+
+        expect(true).not.toBe(false);
+
+- `resolves`
+    Waits for the value (`Promise`) to be *"resolved"* before running the following
+    matcher with the resolved value.
+
+    .. code-block:: javascript
+
+        await expect(Promise.resolve(42)).resolves.toBe(42);
+
+- `rejects`
+    Waits for the value (`Promise`) to be *"rejected"* before running the following
+    matcher with the rejected reason.
+
+    .. code-block:: javascript
+
+        await expect(Promise.reject("error")).rejects.toBe("error");
+
+.. note::
+    The `resolves` and `rejects` modifiers are only available when the value is
+    a promise, and will return a promise that will resolve once the assertion is
+    done.
+
+
+Regular matchers
+----------------
+
+The matchers dictate what to do on the value being tested. Some will take that value
+as-is, while others will *transform* that value before performing the assertion
+on it (i.e. DOM matchers).
+
+Note that the last argument parameter of all matchers is an optional dictionary with additional
+options, in which a custom assertion `message` can be given for added context/specificity.
+
+The first list of matchers are primitive or object based and are the most common ones:
+
+.. js:method:: toBe(expected[, options])
+
+    Expects the received value to be *strictly equal* to the `expected` value.
+
+    - Parameters
+
+        * `expected`: `any`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("foo").toBe("foo");
+            expect({ foo: 1 }).not.toBe({ foo: 1 });
+
+.. js:method:: toBeCloseTo(expected[, options])
+
+    Expects the received value to be *close to* the `expected` value up to a given
+    amount of digits (default is 2).
+
+    - Parameters
+
+        * `expected`: `any`
+        * `options`: `{ message?: string, digits?: number }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(0.2 + 0.1).toBeCloseTo(0.3);
+            expect(3.51).toBeCloseTo(3.5, { digits: 1 });
+
+.. js:method:: toBeEmpty([options])
+
+    Expects the received value to be empty:
+
+        - `iterable`: no items
+        - `object`: no keys
+        - `node`: no content (i.e. no value or text)
+        - anything else: falsy value (`false`, `0`, `""`, `null`, `undefined`)
+
+    - Parameters
+
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect({}).toBeEmpty();
+            expect(["a", "b"]).not.toBeEmpty();
+            expect(queryOne("input")).toBeEmpty();
+
+.. js:method:: toBeGreaterThan(min[, options])
+
+    Expects the received value to be *strictly greater* than `min`.
+
+    - Parameters
+
+        * `min`: `number`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(5).toBeGreaterThan(-1);
+            expect(4 + 2).toBeGreaterThan(5);
+
+.. js:method:: toBeInstanceOf(cls[, options])
+
+    Expects the received value to be an instance of the given `cls`.
+
+    - Parameters
+
+        * `cls`: `Function`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect({ foo: 1 }).not.toBeInstanceOf(Object);
+            expect(document.createElement("div")).toBeInstanceOf(HTMLElement);
+
+.. js:method:: toBeLessThan(max[, options])
+
+    Expects the received value to be *strictly less* than `max`.
+
+    - Parameters
+
+        * `max`: `number`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(5).toBeLessThan(10);
+            expect(8 - 6).toBeLessThan(3);
+
+.. js:method:: toBeOfType(type[, options])
+
+    Expects the received value to be of the given `type`.
+
+    - Parameters
+
+        * `type`: `string`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("foo").toBeOfType("string");
+            expect({ foo: 1 }).toBeOfType("object");
+
+.. js:method:: toBeWithin(min, max[, options])
+
+    Expects the received value to be *between* `min` and `max` (both inclusive).
+
+    - Parameters
+
+        * `min`: `number`
+        * `max`: `number`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(3).toBeWithin(3, 9);
+            expect(-8.5).toBeWithin(-20, 0);
+            expect(100).toBeWithin(50, 100);
+
+.. js:method:: toEqual(expected[, options])
+
+    Expects the received value to be *deeply equal* to the `expected` value.
+
+    - Parameters
+
+        * `expected`: `any`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(["foo"]).toEqual(["foo"]);
+            expect({ foo: 1 }).toEqual({ foo: 1 });
+
+.. js:method:: toHaveLength(length[, options])
+
+    Expects the received value to have a length of the given `length`.
+    Received value can be any `Iterable` or `Object`.
+
+    - Parameters
+
+        * `length`: `number`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("foo").toHaveLength(3);
+            expect([1, 2, 3]).toHaveLength(3);
+            expect({ foo: 1, bar: 2 }).toHaveLength(2);
+            expect(new Set([1, 2])).toHaveLength(2);
+
+.. js:method:: toInclude(item[, options])
+
+    Expects the received value to include an `item` of a given shape.
+
+    Received value can be an iterable or an object (in case it is an object,
+    the `item` should be a key or a tuple representing an entry in that object).
+
+    Note that it is NOT a strict comparison: the item will be matched for deep
+    equality against each item of the iterable.
+
+    - Parameters
+
+        * `item`: `any`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect([1, 2, 3]).toInclude(2);
+            expect({ foo: 1, bar: 2 }).toInclude("foo");
+            expect({ foo: 1, bar: 2 }).toInclude(["foo", 1]);
+            expect(new Set([{ foo: 1 }, { bar: 2 }])).toInclude({ bar: 2 });
+
+.. js:method:: toMatch(matcher[, options])
+
+    Expects the received value to match the given `matcher`.
+
+    - Parameters
+
+        * `matcher`: `string | number | RegExp`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(new Error("foo")).toMatch("foo");
+            expect("a foo value").toMatch(/fo.*ue/);
+
+.. js:method:: toThrow(matcher[, options])
+
+    Expects the received `Function` to throw an error after being called.
+
+    - Parameters
+
+        * `matcher`: `string | number | RegExp`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(() => { throw new Error("Woops!") }).toThrow(/woops/i);
+            await expect(Promise.reject("foo")).rejects.toThrow("foo");
+
+
+DOM matchers
+------------
+
+This next list of matchers are node-based and are used to assert the state of a
+node or a list of nodes. They generally take a :ref:`custom selector <hoot/custom-dom-selectors>`
+as the argument of the `expect` function (although a `Node` or an iterable of `Node`
+is also accepted).
+
+.. js:method:: toBeChecked([options])
+
+    Expects the received `Target` to be `"checked"`, or to be `"indeterminate"`
+    if the homonymous option is set to `true`.
+
+    - Parameters
+
+        * `options`: `{ message?: string, indeterminate?: boolean }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("input[type=checkbox]").toBeChecked();
+
+.. js:method:: toBeDisplayed([options])
+
+    Expects the received `Target` to be *"displayed"*, meaning that:
+
+        - it has a bounding box;
+        - it is contained in the root document.
+
+    - Parameters
+
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(document.body).toBeDisplayed();
+            expect(document.createElement("div")).not.toBeDisplayed();
+
+.. js:method:: toBeEnabled([options])
+
+    Expects the received `Target` to be *"enabled"*, meaning that it
+    matches the `:enabled` pseudo-selector.
+
+    - Parameters
+
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("button").toBeEnabled();
+            expect("input[type=radio]").not.toBeEnabled();
+
+.. js:method:: toBeFocused([options])
+
+    Expects the received `Target` to be *"focused"* in its owner document.
+
+    - Parameters
+
+        * `options`: `{ message?: string }`
+
+.. js:method:: toBeVisible([options])
+
+    Expects the received `Target` to be *"visible"*, meaning that:
+
+        - it has a bounding box;
+        - it is contained in the root document;
+        - it is not hidden by CSS properties.
+
+    - Parameters
+
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(document.body).toBeVisible();
+            expect("[style='opacity: 0']").not.toBeVisible();
+
+.. js:method:: toHaveAttribute(attribute, value[, options])
+
+    Expects the received `Target` to have the given attribute set, and for that
+    attribute value to match the given `value` if any.
+
+    - Parameters
+
+        * `attribute`: `string`
+        * `value`: `string | number | RegExp`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("a").toHaveAttribute("href");
+            expect("script").toHaveAttribute("src", "./index.js");
+
+.. js:method:: toHaveClass(className[, options])
+
+    Expects the received `Target` to have the given class name(s).
+
+    - Parameters
+
+        * `className`: `string | string[]`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("button").toHaveClass("btn btn-primary");
+            expect("body").toHaveClass(["o_webclient", "o_dark"]);
+
+.. js:method:: toHaveCount(amount[, options])
+
+    Expects the received `Target` to contain exactly `amount` element(s).
+    Note that the `amount` parameter can be omitted, in which case the function
+    will expect *at least* one element.
+
+    - Parameters
+
+        * `amount`: `number`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(".o_webclient").toHaveCount(1);
+            expect(".o_form_view .o_field_widget").toHaveCount();
+            expect("ul > li").toHaveCount(4);
+
+.. js:method:: toHaveInnerHTML(expected[, options])
+
+    Expects the `innerHTML` of the received `Target` to match the `expected`
+    value (upon formatting).
+
+    - Parameters
+
+        * `expected`: `string | RegExp`
+        * `options`: `{ message?: string, type?: "html" | "xml", tabSize?: number, keepInlineTextNodes?: boolean }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(".my_element").toHaveInnerHTML(`
+                Some <strong>text</strong>
+            `);
+
+.. js:method:: toHaveOuterHTML(expected[, options])
+
+    Expects the `outerHTML` of the received `Target` to match the `expected`
+    value (upon formatting).
+
+    - Parameters
+
+        * `expected`: `string | RegExp`
+        * `options`: `{ message?: string, type?: "html" | "xml", tabSize?: number, keepInlineTextNodes?: boolean }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect(".my_element").toHaveOuterHTML(`
+                <div class="my_element">
+                    Some <strong>text</strong>
+                </div>
+            `);
+
+.. js:method:: toHaveProperty(property, value[, options])
+
+    Expects the received `Target` to have its given property value match
+    the given `value`. If no value is given: the matcher will instead check that
+    the given property exists on the target.
+
+    - Parameters
+
+        * `property`: `string`
+        * `value`: `any`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("button").toHaveProperty("tabIndex", 0);
+            expect("input").toHaveProperty("ontouchstart");
+            expect("script").toHaveProperty("src", "./index.js");
+
+.. js:method:: toHaveRect(rect[, options])
+
+    Expects the `DOMRect` of the received `Target` to match the given `rect` object.
+    The `rect` object can either be:
+
+        - a `DOMRect` object;
+        - a CSS selector string (to get the rect of the *only* matching element);
+        - a node.
+
+    If the resulting `rect` value is a node, then both nodes' rects will be compared.
+
+    - Parameters
+
+        * `rect`: `Partial<DOMRect> | Target`
+        * `options`: `{ message?: string, trimPadding?: boolean }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("button").toHaveRect({ x: 20, width: 100, height: 50 });
+            expect("button").toHaveRect(".container");
+
+.. js:method:: toHaveStyle(style[, options])
+
+    Expects the received `Target` to match the given style properties.
+
+    - Parameters
+
+        * `style`: `string | Record<string, string | RegExp>`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("button").toHaveStyle({ color: "red" });
+            expect("p").toHaveStyle("text-align: center");
+
+.. js:method:: toHaveText(text[, options])
+
+    Expects the `text` content of the received `Target` to either:
+
+        - be strictly equal to a given string;
+        - match a given regular expression.
+
+    Note: `innerHTML` is used to retrieve the text content to take CSS visibility
+    into account. This also means that text values from child elements will be
+    joined using a line-break as separator.
+
+    - Parameters
+
+        * `text`: `string | RegExp`
+        * `options`: `{ message?: string, raw?: boolean }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("p").toHaveText("lorem ipsum dolor sit amet");
+            expect("header h1").toHaveText(/odoo/i);
+
+.. js:method:: toHaveValue(value[, options])
+
+    Expects the value of the received `Target` to either:
+
+        - be strictly equal to a given string or number;
+        - match a given regular expression;
+        - contain file objects matching the given `files` list.
+
+    - Parameters
+
+        * `value`: `any`
+        * `options`: `{ message?: string }`
+
+    - Examples
+
+        .. code-block:: javascript
+
+            expect("input[type=email]").toHaveValue("john@doe.com");
+            expect("input[type=file]").toHaveValue(new File(["foo"], "foo.txt"));
+            expect("select[multiple]").toHaveValue(["foo", "bar"]);
+
+Static methods
+--------------
+
+The `expect` helper function also contains static methods that can be used to run
+through a detached testing flow that isn't bound to one specific value at a certain
+moment.
+
+These methods are mainly used to register steps or errors in the scope of the current
+test, and to evaluate them later on.
+
+.. js:function:: expect.assertions(expected)
+
+    :param number expected:
+
+    Expects the current test to have the `expected` amount of assertions. This
+    number cannot be less than 1.
+
+    .. note::
+        It is generally preferred to use :js:meth:`expect.step` and :js:meth:`expect.verifySteps`
+        instead as it is more reliable and allows to test more extensively.
+
+.. js:function:: expect.errors(expected)
+
+    :param number expected:
+
+    Expects the current test to have the `expected` amount of errors.
+
+    This also means that from the moment this function is called, the test will
+    accept that amount of errors before being considered as failed.
+
+.. js:function:: expect.step(value)
+
+    :param unknown value:
+
+    Registers a step for the current test, that can be consumed by :js:meth:`expect.verifySteps`.
+    Unconsumed steps will fail the test.
+
+.. js:function:: expect.verifyErrors(errors[, options])
+
+    :param unknown[] errors:
+    :param { message?\: string } options:
+    :returns: `boolean`
+
+    Expects the received matchers to match the errors thrown since the start of
+    the test or the last call to :js:meth:`expect.verifyErrors`. Calling this matcher
+    will reset the list of current errors.
+
+    .. code-block:: javascript
+
+        expect.verifyErrors([/RPCError/, /Invalid domain AST/]);
+
+.. js:function:: expect.verifySteps(steps[, options])
+
+    :param unknown[] steps:
+    :param { ignoreOrder?\: boolean, message?\: string, partial?\: boolean } options:
+    :returns: `boolean`
+
+    Expects the received steps to be equal to the steps emitted since the start
+    of the test or the last call to :js:meth:`expect.verifySteps`. Calling this
+    matcher will reset the list of current steps.
+
+    .. code-block:: javascript
+
+        expect.step("web_read_group");
+        expect.step([1, 2]);
+        expect.verifySteps(["web_read_group", [1, 2]]);
+
+.. js:function:: expect.waitForErrors(errors[, options])
+
+    :param unknown[] errors:
+    :param { message?\: string } options:
+    :returns: `Promise<boolean>`
+
+    Same as :js:meth:`expect.verifyErrors`, but will not immediatly fail if errors
+    are not caught yet, and will instead wait for a certain timeout (default: 2000ms)
+    to allow errors to be caught later.
+
+    Checks are performed initially, at the end of the timeout, and each time an
+    error is detected.
+
+    .. code-block:: javascript
+
+        fetch("invalid/url");
+        await expect.waitForErrors([/RPCError/]);
+
+.. js:function:: expect.waitForSteps(steps[, options])
+
+    :param unknown[] steps:
+    :param { ignoreOrder?\: boolean, message?\: string, partial?\: boolean } options:
+    :returns: `Promise<boolean>`
+
+    Same as :js:meth:`expect.verifySteps`, but will not immediatly fail if steps
+    have not been registered yet, and will instead wait for a certain timeout (default:
+    2000ms) to allow steps to be registered later.
+
+    Checks are performed initially, at the end of the timeout, and each time
+    a step is registered.
+
+    .. code-block:: javascript
+
+        // ... step on each 'web_read_group' call
+        fetch(".../call_kw/web_read_group");
+        await expect.waitForSteps(["web_read_group"]);
+
+DOM: queries
+============
+
+.. _hoot/custom-dom-selectors:
+
+Custom DOM selectors
+--------------------
+
+Here's a brief section on DOM selectors in Hoot, as they support additional pseudo-classes
+that can be used to target elements based on non-standard features, such as their
+text content or their global position in the document.
+
+- `:contains(text)`
+    matches nodes whose text content matches the given `text`
+
+    - given *text* supports regular expression syntax (e.g. `:contains(/^foo.+/)`) and is
+      case-insensitive (unless using the `i` flag at the end of the regex)
+
+- `:displayed`
+    matches nodes that are *"displayed"* (see `isDisplayed`)
+
+- `:empty`
+    matches nodes that have an empty content (value or text content)
+
+- `:eq(n)`
+    returns the *nth* node based on its global position (0-based index);
+
+- `:first`
+    returns the first node matching the selector (in the whole document)
+
+- `:focusable`
+    matches nodes that can be *"focused"* (see `isFocusable`)
+
+- `:hidden`
+    matches nodes that are *not* *"visible"* (see `isVisible`)
+
+- `:iframe`
+    matches nodes that are `<iframe>` elements, and returns their `body` if it is ready
+
+- `:last`
+    returns the last node matching the selector (in the whole document)
+
+- `:selected`
+    matches nodes that are selected (e.g. `<option>` elements)
+
+- `:shadow`
+    matches nodes that have shadow roots, and returns their shadow root
+
+- `:scrollable`
+    matches nodes that are scrollable (see `isScrollable`)
+
+- `:value(text)`
+    matches nodes whose value matches the given `text`
+
+    - given *text* supports regular expression syntax (e.g. `:value(/^foo.+/)`) and is
+      case-insensitive (unless using the `i` flag at the end of the regex)
+
+- `:visible`
+    matches nodes that are *"visible"* (see `isVisible`)
+
+Query & node properties helpers
+-------------------------------
+
+Hoot provides helpers to query nodes and some of their properties in a streamlined
+and elegant way. This can mainly be done through the use of `queryX` helpers:
+
+.. js:function:: queryAll(target[, options])
+
+    Returns a list of nodes matching the given `Target`.
+    This function can either be used as a `template literal tag <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates>`_
+    (only supports string selector without options) or invoked the usual way.
+
+    The target can be:
+
+        - a `Node` (or an iterable of nodes), or `Window` object;
+        - a `Document` object (which will be converted to its body);
+        - a string representing a :ref:`custom selector <hoot/custom-dom-selectors>`
+          (which will be queried from the `root` option).
+
+    An `options` object can be specified to filter [#]_ the results:
+
+        - `count`: the exact number of nodes to match (throws an error if the number of nodes
+          doesn't match);
+        - `displayed`: whether the nodes must be "displayed" (see `isDisplayed`);
+        - `focusable`: whether the nodes must be "focusable" (see `isFocusable`);
+        - `root`: the root node to query the selector in (defaults to the current fixture);
+        - `visible`: whether the nodes must be "visible" (see `isVisible`).
+          * This option implies `displayed`
+
+    .. [#] these filters (except for `count` and `root`) achieve the same result as using their homonym
+        pseudo-classes on the final group of the given selector string, e.g.:
+
+        .. code-block:: javascript
+
+            // These 2 will return the same result
+            queryAll`ul > li:visible`;
+            queryAll("ul > li", { visible: true });
+
+    :returns: `Node[]`
+
+.. js:function:: queryAllAttributes(target, attribute[, options])
+
+    Performs a :js:meth:`queryAll` on the given `target` and returns
+    a list of attribute values.
+
+    :returns: `string[]` list of attribute values
+
+.. js:function:: queryAllProperties(target, property[, options])
+
+    Performs a :js:meth:`queryAll` on the given `target` and returns
+    a list of property values.
+
+    :returns: `unknown[]` list of property values
+
+.. js:function:: queryAllTexts(target[, options])
+
+    Performs a :js:meth:`queryAll` on the given `target` and returns
+    a list of text contents.
+
+    :returns: `string[]` list of text contents
+
+.. js:function:: queryAllValues(target[, options])
+
+    Performs a :js:meth:`queryAll` on the given `target` and returns
+    a list of values.
+
+    :returns: `string[]` a list of values
+
+.. js:function:: queryAttribute(target, attribute[, options])
+
+    Performs a :js:meth:`queryOne` with the given arguments and returns
+    the value of the given `attribute` of the matching node.
+
+    :returns: `string` the attribute value
+
+.. js:function:: queryFirst(target[, options])
+
+    Performs a :js:meth:`queryAll` with the given arguments and returns
+    the first result or `null`.
+
+    :returns: `Node` | `null` the first matching node
+
+.. js:function:: queryOne(target[, options])
+
+    Performs a :js:meth:`queryAll` with the given arguments, along with
+    a forced `count: 1` option to ensure only one node matches the given `Target`.
+
+    The returned value is a single node instead of a list of nodes.
+
+    :returns: `Node` a single node
+
+.. js:function:: queryText(target[, options])
+
+    Performs a :js:meth:`queryOne` with the given arguments and returns
+    the *text* of the matching node.
+
+    :returns: `string` text of the matching node
+
+.. js:function:: queryValue(target[, options])
+
+    Performs a :js:meth:`queryOne` with the given arguments and returns
+    the *value* of the matching node.
+
+    :returns: `string` value of the matching node
+
+All of the above helpers are synchronous, meaning that they will attempt to query
+nodes instantly. Although some use cases require the element to be awaited for an
+arbitrary amount of time, unknown in advance due to UI fetching and rendering complexity.
+
+Hoot provides 2 methods to wait for an element to appear / disappear within a certain
+time frame (by default: `200` milliseconds) for such cases:
+
+.. js:function:: waitFor(target[, options])
+
+    Combination of :js:meth:`queryAll` and :js:meth:`waitUntil`:
+    waits for a given target to match elements in the DOM and returns the first
+    matching node when it appears (or immediately if it is already present).
+
+    :returns: `Promise<Node>` containing the first matching node
+
+.. js:function:: waitForNone(target[, options])
+
+    Opposite of :js:meth:`waitFor` waits for a given target to disappear from the DOM.
+
+    :returns: `Promise<number>` containing the number of matching nodes
+
+
+DOM: interaction helpers
+========================
+
+Along with querying elements, it is often required to interact with them.
+As such, Hoot provides helpers to simulate various user interactions on elements.
+
+These can be split into 2 types based on their parameters: **pointer-based** interaction
+helpers, and the **other** ones.
+
+Pointer interaction helpers:
+----------------------------
+
+Pointer interaction helpers (such as :js:meth:`click` or :js:meth:`drag`) will simulate
+actual pointer movements and events on the given target, and on any previous element
+the pointer was *supposed* to have been.
+
+.. js:function:: check(target[, options])
+
+    Ensures that the given `Target` is checked.
+
+    If it is not checked, a :js:meth:`click` is simulated on the input.
+    If the input is still not checked after the click, an error is thrown.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        check("input[type=checkbox]"); // Checks the first <input> checkbox element
+
+.. js:function:: click(target[, options])
+
+    Performs a click sequence on the given `Target`.
+
+    The event sequence is as follows:
+
+        - `pointerdown`
+        - [desktop] `mousedown`
+        - [touch] `touchstart`
+        - [target is not active element] `blur`
+        - [target is focusable] `focus`
+        - `pointerup`
+        - [desktop] `mouseup`
+        - [touch] `touchend`
+        - `click`
+        - `dblclick` if click is not prevented & current click count is even
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        click("button"); // Clicks on the first <button> element
+
+.. js:function:: dblclick(target[, options])
+
+    Performs two :js:meth:`click` sequences on the given `Target`.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        dblclick("button"); // Double-clicks on the first <button> element
+
+.. js:function:: drag(target[, options])
+
+    Starts a drag sequence on the given `Target`.
+
+    Returns a set of helper functions to direct the sequence:
+
+        - `moveTo`: moves the pointer to the given target;
+        - `drop`: drops the dragged element on the given target (if any);
+        - `cancel`: cancels the drag sequence.
+
+    :returns: `Promise<DragHelpers>`
+
+    .. code-block:: javascript
+
+        drag(".card:first").drop(".card:last"); // Drags the first card onto the last one
+
+        drag(".card:first").moveTo(".card:last").drop(); // Same as above
+
+        const { cancel, moveTo } = await drag(".card:first"); // Starts the drag sequence
+        moveTo(".card:eq(3)"); // Moves the dragged card to the 4th card
+        cancel(); // Cancels the drag sequence
+
+.. js:function:: hover(target[, options])
+
+    Performs a hover sequence on the given `Target`.
+
+    The event sequence is as follows:
+
+        - `pointerover`
+        - [desktop] `mouseover`
+        - `pointerenter`
+        - [desktop] `mouseenter`
+        - `pointermove`
+        - [desktop] `mousemove`
+        - [touch] `touchmove`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        hover("button"); // Hovers the first <button> element
+
+.. js:function:: pointerDown(target[, options])
+
+    Performs a pointer down on the given `Target`.
+
+    The event sequence is as follows:
+
+        - `pointerdown`
+        - [desktop] `mousedown`
+        - [touch] `touchstart`
+        - [target is not active element] `blur`
+        - [target is focusable] `focus`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        pointerDown("button"); // Focuses to the first <button> element
+
+.. js:function:: pointerUp(target[, options])
+
+    Performs a pointer up on the given `Target`.
+
+    The event sequence is as follows:
+
+        - `pointerup`
+        - [desktop] `mouseup`
+        - [touch] `touchend`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        pointerUp("body"); // Triggers a pointer up on the <body> element
+
+.. js:function:: scroll(target, position[, options])
+
+    Performs a scroll event sequence on the given `Target`.
+
+    The event sequence is as follows:
+
+        - [desktop] `wheel`
+        - `scroll`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        scroll("body", { y: 0 }); // Scrolls to the top of <body>
+
+.. js:function:: setInputRange(target, value[, options])
+
+    Sets the given value to the current "input[type=range]" `Target`.
+
+    The event sequence is as follows:
+
+        - `pointerdown`
+        - `input`
+        - `change`
+        - `pointerup`
+
+    :returns: `Promise<Event[]>`
+
+.. js:function:: uncheck(target[, options])
+
+    Ensures that the given `Target` is unchecked.
+
+    If it is checked, a :js:meth:`click` is triggered on the input.
+    If the input is still checked after the click, an error is thrown.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        uncheck("input[type=checkbox]"); // Unchecks the first <input> checkbox element
+
+Other interaction helpers:
+--------------------------
+
+Other interaction helpers will not have a `target` parameter. It is not needed,
+since pressing keys on a keyboard (for example) is done on the current *active element*.
+
+.. js:function:: clear([options])
+
+    Clears the value of the current *active element*.
+
+    This is done using the following sequence:
+
+        - pressing `"Control"` & `"A"` to select the whole value;
+        - pressing `"Backspace"` to delete the value;
+        - (optional) triggering a `"change"` event by pressing `"Enter"`.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        clear(); // Clears the value of the current active element
+
+.. js:function:: edit(value[, options])
+
+    Combination of :js:meth:`clear` and :js:meth:`fill`:
+
+        - first, clears the input value (if any)
+        - then fills the input with the given value
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        fill("foo"); // Types "foo" in the active element
+        edit("Hello World"); // Replaces "foo" by "Hello World"
+
+.. js:function:: fill(value[, options])
+
+    Fills the current *active element* with the given `value`. This helper is intended
+    for `<input>` and `<textarea>` elements, with the exception of `"checkbox"` and
+    `"radio"` types, which should be selected using the `check` helper.
+
+    If the target is an editable input, its string `value` will be input one character
+    at a time, each generating its corresponding keyboard event sequence. This behavior
+    can be overridden by passing the `instantly` option, which will instead simulate
+    a `control` + `v` keyboard sequence, resulting in the whole text being pasted.
+
+    Note that the given value is appended to the current value of the element.
+
+    If the active element is a `<input type="file"/>`, the `value` should be a
+    `File`/list of `File` object(s).
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        fill("Hello World"); // Types "Hello World" in the active element
+        fill("Hello World", { instantly: true }); // Pastes "Hello World" in the active element
+        fill(new File(["Hello World"], "hello.txt")); // Uploads a file named "hello.txt" with "Hello World" as content
+
+.. js:function:: keyDown(keyStrokes[, options])
+
+    Performs a key down sequence on the current *active element*.
+
+    The event sequence is as follows:
+
+        - `keydown`
+
+    Additional actions will be performed depending on the key pressed:
+
+        - `Tab`: focus next (or previous with `shift`) focusable element;
+        - `c`: copy current selection to clipboard;
+        - `v`: paste current clipboard content to current element;
+        - `Enter`: submit the form if the target is a `<button type="button">` or
+          a `<form>` element, or trigger a `change` event on the target if it is
+          an `<input>` element;
+        - `Space`: trigger a `click` event on the target if it is an `<input type="checkbox">`
+          element.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        keyDown(" "); // Space key
+
+.. js:function:: keyUp(keyStrokes[, options])
+
+    Performs a key up sequence on the current *active element*.
+
+    The event sequence is as follows:
+
+        - `keyup`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        keyUp("Enter");
+
+.. js:function:: leave([options])
+
+    Performs a leave sequence on the current `Window`.
+
+    The event sequence is as follows:
+
+        - `pointermove`
+        - [desktop] `mousemove`
+        - [touch] `touchmove`
+        - `pointerout`
+        - [desktop] `mouseout`
+        - `pointerleave`
+        - [desktop] `mouseleave`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        leave("button"); // Moves out of <button>
+
+.. js:function:: press(keyStrokes[, options])
+
+    Performs a keyboard event sequence on the current *active element*.
+
+    The event sequence is as follows:
+
+        - `keydown`
+        - `keyup`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        pointerDown("button[type=submit]"); // Moves focus to <button>
+        keyDown("Enter"); // Submits the form
+
+        keyDown("Shift+Tab"); // Focuses previous focusable element
+
+        keyDown(["ctrl", "v"]); // Pastes current clipboard content
+
+.. js:function:: resize([dimensions[, options]])
+
+    Performs a resize event sequence on the current `Window`.
+
+    The event sequence is as follows:
+
+        - `resize`
+
+    The target will be resized to the given dimensions, enforced by `!important` style
+    attributes.
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        resize("body", { width: 1000, height: 500 }); // Resizes <body> to 1000x500
+
+.. js:function:: select(value[, options])
+
+    Performs a selection event sequence on the current active element. This helper
+    is intended for `<select>` elements only.
+
+    The event sequence is as follows:
+
+        - `change`
+
+    :returns: `Promise<Event[]>`
+
+    .. code-block:: javascript
+
+        click("select[name=country]"); // Focuses <select> element
+        select("belgium"); // Selects the <option value="belgium"> element
+
+.. js:function:: setInputFiles(files[, options])
+
+    Gives the given `File` list to the current file input. This helper only
+    works if a file input has been previously interacted with (by clicking on it).
+
+    :returns: `Promise<Event[]>`
+
+.. js:function:: unload([options])
+
+    Triggers a "beforeunload" event on the current `Window`.
+
+    :returns: `Promise<Event[]>`
+
+
+Mocks
+=====
+
+By default, a lot of low-level features are mocked by Hoot: `clipboard`, `fetch`, `localStorage`,
+etc. These mocks are intended to not produce any side-effect that would disturb the test runner
+or the context of other tests, while still providing the same interface to allow tests to rely
+on these features seamlessly.
+
+There is also a need (most of the time) to force actions on these features or change their
+behavior for a test, so there exist helpers to interact with these mocked features. The following
+sections will list the main mocked features and the means to interact with them.
+
+Time
+----
+
+Most asynchronous features are mocked: "timers" (`setTimeout`, `setInterval` and
+`requestAnimationFrame`), `Date` and `performance` all behave normally, but can be canceled or
+sped-up manually to considerably shorten the actual duration of tests. For example: all "timers"
+are canceled at the end of each test to avoid side-effects for the next one.
+
+    .. important::
+        There are 2 main timing behaviors that are *NOT* mocked:
+
+            - `Promise` objects and related API;
+            - OWL's timer functions: to wait for OWL rendering functions, you'll have
+              to resort to the `animationFrame` helper.
+
+Related helpers
+~~~~~~~~~~~~~~~
+
+.. js:function:: advanceFrame(frameCount)
+
+    Calls `advanceTime` with the duration it would take for a given `frameCount`
+    amount of frames to have rendered in the UI (i.e. (1000 / current FPS) x frame count).
+
+.. js:function:: advanceTime(ms)
+
+    Advances the current time by the given amount of milliseconds. This will
+    affect all timeouts, intervals, animations and date objects.
+
+    It returns a promise resolved after all related callbacks have been executed.
+
+    :returns: `Promise<number>` time consumed by timers (in ms)
+
+.. js:function:: animationFrame()
+
+    Returns a promise resolved after the next animation frame, typically allowing
+    Owl components to render.
+
+    :returns: `Promise<void>`
+
+.. js:function:: cancelAllTimers()
+
+    Cancels all current timeouts, intervals and animations.
+
+.. js:function:: delay()
+
+    Returns a promise resolved after a given amount of milliseconds (default to `0`).
+
+    .. code-block:: javascript
+
+        await delay(1000); // waits for 1 second
+
+    :returns: `Promise<void>`
+
+.. js:function:: microTick()
+
+    Returns a promise resolved after the next microtask tick.
+
+    :returns: `Promise<void>`
+
+.. js:function:: mockDate(date[, tz])
+
+    Mocks the current date and time, and also the time zone if any.
+
+    Date can either be an object describing the date and time to mock, or a
+    string in SQL or ISO format (time and millisecond values can be omitted).
+    See :js:meth:`mockTimeZone` for the time zone params.
+
+    .. code-block:: javascript
+
+        mockDate("2023-12-25T20:45:00"); // 2023-12-25 20:45:00 UTC
+        mockDate({ year: 2023, month: 12, day: 25, hour: 20, minute: 45 }); // same as above
+        mockDate("2019-02-11 09:30:00.001", +2);
+
+.. js:function:: mockTimeZone(tz)
+
+    Mocks the current time zone.
+
+    Time zone can either be a locale, a time zone or an offset.
+
+    Returns a function restoring the default zone.
+
+    .. code-block:: javascript
+
+        mockTimeZone(+1); // UTC + 1
+        mockTimeZone("Europe/Brussels"); // UTC + 1 (or UTC + 2 in summer)
+        mockTimeZone("ja-JP"); // UTC + 9
+
+.. js:function:: runAllTimers([preventTimers])
+
+    Calculates the amount of time needed to run all current timeouts, intervals and
+    animations, and then advances the current time by that amount.
+
+    :returns: `Promise<void>`
+
+.. js:function:: setFrameRate(frameRate)
+
+    Sets the current frame rate (in fps) used by animation frames (default to 60fps).
+
+.. js:function:: tick()
+
+    Returns a promise resolved after the next task tick.
+
+    :returns: `Promise<void>`
+
+.. js:function:: waitUntil(predicate[, options])
+
+    Returns a promise fulfilled when the given `predicate` returns a truthy value, with the value of
+    the promise being the return value of the `predicate`.
+
+    The `predicate` is run once initially and then each time the DOM is mutated (see `observe` for
+    more information).
+
+    The promise automatically rejects after a given `timeout` (defaults to 5 seconds).
+
+    :returns: `Promise<unknown>` promise with the return value of the predicate
+
+Network
+-------
+
+In general, we don't want to perform actual network calls in tests. To ensure this, all calls
+to `fetch` and `XMLHttpRequest` have been re-routed to a function given to
+:js:meth:`mockFetch`.
+
+.. note::
+    In Odoo, this is generally implicitly handled by a :ref:`MockServer <mock-server/configuration>`
+    which is spawned by the mock environment, i.e. any time a component is rendered using the
+    :ref:`mountWithCleanup <web-test-helpers/components>` helper.
+
+Related helpers
+~~~~~~~~~~~~~~~
+
+.. js:function:: mockFetch([fetchFn])
+
+    Mocks the fetch function by replacing it with a given `fetchFn`.
+
+    The return value of `fetchFn` is used as the response of the mocked fetch, or
+    wrapped in a `MockResponse` object if it does not meet the required format.
+
+    .. code-block:: javascript
+
+        mockFetch((input, init) => {
+            if (input === "/../web_search_read") {
+                return { records: [{ id: 3, name: "john" }] };
+            }
+            // ...
+        });
+        mockFetch((input, init) => {
+            if (input === "/translations") {
+                const translations = {
+                    "Hello, world!": "Bonjour, monde !",
+                    // ...
+                };
+                return new Response(JSON.stringify(translations));
+            }
+        });
+
+.. js:function:: mockWebSocket([onWebSocketConnected])
+
+    Activates mock WebSocket classe:
+
+        - websocket connections will be handled by `window.fetch`
+          (see :js:meth:`mockFetch`);
+        - the `onWebSocketConnected` callback will be called after a websocket has been created.
+
+.. js:function:: mockWorker([onWorkerConnected])
+
+    Activates mock `Worker` and `SharedWorker` classes:
+
+        - actual code fetched by worker URLs will then be handled by `window.fetch`
+          (see :js:meth:`mockFetch`);
+        - the `onWorkerConnected` callback will be called after a worker has been created.
+
+Notable global features
+-----------------------
+
+The following features may not have any specific mocked feature added, but they do work as
+expected without changing the actual properties they were meant to:
+
+- `Document <https://developer.mozilla.org/en-US/docs/Web/API/Document>`_
+
+    Both `title` and `cookie` can be set and read without changing the actual properties
+    of the current document.
+
+- `History <https://developer.mozilla.org/en-US/docs/Web/API/History>`_
+
+    The `history` API is mocked and bound to the `mockLocation` object to return the same
+    values and provide consistency.
+
+- `Location <https://developer.mozilla.org/en-US/docs/Web/API/Location>`_
+
+    Hoot returns a `mockLocation` object to use instead of `window.location`, but this relies on
+    the use of an indirection in the actual production code.
+
+    .. important::
+        This feature will only work if an indirection is set between production code and
+        calls to `window.location`. In Odoo, it works because the `@web/core/browser` module
+        provides such an indirection, and that module is mocked in test environments to redirect
+        to the `mockLocation` object.
+
+- `Navigator <https://developer.mozilla.org/en-US/docs/Web/API/Navigator>`_
+
+    Most used navigator features, such as the `clipboard` API and `userAgent`, have
+    been mocked to hijack their actual behaviors. Its `permissions` object has been bound
+    to a global mock of the permissions API.
+
+- `Notification <https://developer.mozilla.org/en-US/docs/Web/API/Notification>`_
+
+    Notifications have been mocked, with the "notification" permissions bound to the global
+    mocked permissions API.
+
+- `Permissions <https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API>`_
+
+    Permissions can enable or disable other APIs by being given the `"granted"`
+    or `"denied"` statuses. This can be done through the `mockPermission` helper.
+
+- `Storage <https://developer.mozilla.org/en-US/docs/Web/API/Storage>`_
+
+    `localStorage` and `sessionStorage` both point to "virtual" storages.
+
+- `Touch <https://developer.mozilla.org/en-US/docs/Web/API/Touch_events>`_
+
+    Touch features can be force-activated or deactivated globally for a given test/suite
+    using the :js:meth:`mockTouch` helper. It will mock both the presence
+    of touch handlers like `ontouchstart` on window, as well as the `"pointer"` media
+    being set to `fine` or `coarse`.
+
+Related helpers
+~~~~~~~~~~~~~~~
+
+.. js:function:: mockPermission(name[, value])
+
+    Sets the given value for the given permission. This allows to enable or prevent
+    certain APIs (see the `Permissions API <https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API>`_).
+
+    .. code-block:: javascript
+
+        // Prevents the whole notification API from working
+        mockPermission("notifications", "denied");
+
+.. js:function:: mockTouch(setTouch)
+
+    Toggles touch features on or off in the current `Window`.
diff --git a/content/developer/reference/frontend/unit_testing/mock_server.rst b/content/developer/reference/frontend/unit_testing/mock_server.rst
new file mode 100644
index 0000000000..a20b9de4aa
--- /dev/null
+++ b/content/developer/reference/frontend/unit_testing/mock_server.rst
@@ -0,0 +1,383 @@
+===========
+Mock server
+===========
+
+Rationale
+=========
+
+Test cases can range in complexity; from testing the return value of a simple helper
+function, to rendering an entire webclient to simulate interactions across several
+components/services.
+
+In the latter cases, many interactions will trigger server requests, without
+which the components or features will stop functioning properly. However, it is
+important that these requests *do not* land on the actual server, as they could
+affect the database, which is definitely not something a test should be doing.
+
+To overcome this, each request should be intercepted and replaced by a function
+emulating actual server responses with test (i.e. fake) data.
+
+Since some of these requests are very common (e.g. ORM calls, such as `web_search_read`
+or `web_save`, or other methods such as `get_views`), a mock server has been
+implemented by default for every test that spawns an :abbr:`env (Odoo environment)` [#]_.
+
+These mock servers act independently for each test, can be configured separately,
+and provide out of the box helpers for the most used routes in Odoo.
+
+.. [#] A mock server is needed as soon as an environment is spawned because some :doc:`services <../services>`
+    do send server requests as soon as they start.
+
+Overview
+========
+
+A mock server is actually quite simple in itself: it is an object containing a *collection*
+of all defined mock models, and a *mapping* between routes and callbacks returning
+the test data.
+
+The mock models themselves hold most of the CRUD logic, as well as the data used
+to simulate server records.
+
+Once a mock server starts, it hijacks *all* server requests, and for each of them
+it will check in its *mapping* whether one of its registered routes matches
+the requested URL. The most notable example of its pre-defined routes is
+`/web/dataset/call_kw`, which is responsible for calling an ORM method on the
+appropriate mock model.
+
+.. note::
+    Like most test helpers not provided by Hoot, mock server-related helpers and
+    classes can be found in the `"@web/../tests/web_test_helpers"` module.
+
+.. _mock-server/configuration:
+
+Configuration
+=============
+
+By default, a mock server is *"empty"*, meaning that it has no defined mock model.
+
+This does not mean that it is useless though, as it will already handle a few pre-defined
+routes, such as the ones responsible for fetching `menus` and `translations`, which
+are spawned by :doc:`services <../services>` as soon as an `env` is spawned.
+
+But this means that ORM methods will fail, as the model that they target has not
+been defined yet.
+
+To create and define a mock model, you need 2 things:
+
+- a `class` extending the `models.Model` class;
+
+    - special keys prefixed with a `_` act as metadata holders, like in Python
+      (e.g. `_name`, `_order`, `_description`, etc.) [#]_ [#]_;
+
+    - `_records` holds the list of objects representing fake record data;
+
+    - `_views` can be a mapping of view types and XML arches;
+
+    - other `public class fields <public-class-fields_>`_
+      will be interpreted as fields (by calling the appropriate method from `fields`);
+
+    - model-specific methods (such as `has_group` for `"res.users"`) can also be
+      defined here.
+
+- calling `defineModels` with the class defined above.
+
+.. [#] Only a subset of these special keys will have an actual effect. For example,
+    `_inherit` will not work as intended, prefer standard class extension.
+
+.. [#] These can be altered by each test without thinking about cleaning up: any change
+    performed on a special key will be reverted at the end of a test.
+
+Here is a basic example of a simple, fake, `"res.partner"` model:
+
+.. code-block:: javascript
+
+    import { defineModels, fields, models } from "@web/../tests/web_test_helpers";
+
+    class ResPartner extends models.Model {
+        _name = "res.partner";
+
+        name = fields.Char({ required: true );
+
+        _records = [
+            { name: "Mitchel Admin" },
+        ];
+
+        _views = {
+            form: /* xml */`
+                <form>
+                    <field name="name" />
+                </form>
+            `,
+            list: /* xml */`
+                <list>
+                    <field name="display_name" />
+                </list>
+            `,
+        };
+    }
+
+    defineModels({ ResPartner });
+
+This code will make these data available for *all* tests in the current test file.
+Of course, defining a class and calling `defineModels` can also be done from *within*
+a given test to limit the scope of that model to the current test.
+
+Other methods such as `defineMenus`, `defineActions` or `defineParams` can also
+be used to configure the current mock server. Most of their API is quite straightforward
+(i.e. they receive JSON-like descriptions of menus, actions, etc.).
+
+Mock models: requests
+---------------------
+
+Many test cases only require one or a few mock models to work. But sometimes,
+it is either too bothersome to implement the mocking logic within a model, or a
+*route* (i.e. server request URL) is simply not associated to a Python model at all.
+
+In such cases, the `onRpc` method is to be called, to associate a route or an ORM
+method to a callback.
+
+.. note::
+    Multiple `onRpc` calls can be associated to the same route / ORM method;
+    in which case they will be called sequentially from last to first defined.
+    Returning a *non-null-or-undefined* value will interrupt the current chain,
+    and return that value as final result of the server request.
+
+It can be used in 4 different ways:
+
+`onRpc`: with a route (`"/"`)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the first argument is a `string` starting with a `"/"`, the callback
+is expected to be a *route* callback, receiving a `Request_`
+object:
+
+.. code-block:: javascript
+
+    onRpc("/route/to/test", async (request) => {
+        const { ids }  = await request.json();
+        expect.step(ids);
+        return {};
+    });
+
+By default, the return value of these callbacks are wrapped within the `body`
+of a mock `Response_` object.
+
+This is fine for most use-cases, but sometimes the callback needs to respond with
+a `Response_` object with custom `status` or `headers`.
+
+In such cases, an *optional* dictionary can be passed as a 3rd argument to specify
+whether the callback is to be considered *"pure"*, meaning that its return value
+should be returned as-is to the server caller:
+
+.. code-block:: javascript
+
+    onRpc(
+        "/not/found",
+        () => new Response("{}", { status: 404 }),
+        { pure: true }
+    );
+
+.. note::
+    Using *"pure"* request callbacks can also be used to return anything else than
+    a `Response_` object, in which case the returned value will still be wrapped
+    in the body of a mock `Response_` to comply with the `fetch_` / `XMLHttpRequest_`
+    APIs.
+
+`onRpc`: with method name(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the first argument is a `string` *NOT* starting with a `"/"` or a list of `strings`,
+the callback is expected to be an ORM callback, only called when the request's `method`
+matches the one given as argument.
+
+The callback will receive an object containing:
+
+- the *spread* `params` value contained in the request body (typically: `args`,
+  `kwargs`, `model` and `method`);
+
+- a `parent()` function, which when invoked will call the defined ORM callback *preceding*
+  this one;
+
+- a `route` key, containing the `pathname` of the request (typically: `/web/dataset/call_kw`);
+
+- the `request` object.
+
+.. code-block:: javascript
+
+    onRpc("web_read", async ({ args, parent }) => {
+        const result = parent();
+        expect.step(args[0]); // Contains the list of IDs
+        result.some_meta_data = { foo: "bar" };
+        return result;
+    });
+
+`onRpc`: with model name(s) AND method name(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When:
+
+- the first argument is a `string` *NOT* starting with a `"/"` or a list of `strings`;
+
+- the second argument is also a `string` or a list of `strings`;
+
+Then the callback is expected to be an ORM callback, only called when the request's
+`method` *AND* `model` match the ones given in the arguments.
+
+This works just the same as the above shape, with an added `model` filter:
+
+.. code-block:: javascript
+
+    onRpc("web_read", "res.partner", ({ args }) => {
+        expect.step(args[0]);
+    });
+
+`onRpc`: for *every* ORM method/model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the *only* argument is a callback, it is expected to be an ORM callback to
+be called for *every* ORM call:
+
+.. code-block:: javascript
+
+    onRpc(({ method }) => {
+        expect.step(method); // Will step every ORM method call on every model
+    });
+
+Mock models: fields
+-------------------
+
+Model fields can be declared in 2 ways:
+
+- as `public class fields <public-class-fields_>`_;
+
+- under the `_fields` special key. For example:
+
+    .. code-block:: javascript
+
+        test("test view with date fields", async () => {
+            // `_fields` can be assigned over, or extended directly.
+            ResPartner._fields.date = fields.Date({ string: "Registration date" });
+        });
+
+Field constructors can take a parameters dictionary to dictate their behaviour.
+It will be required for some of them, like relational fields, which need a `relation`
+property to work correctly.
+
+There are limits to what can be done with a mock field compared to an actual Python
+server field, but expect the most basic properties to be supported:
+`readonly`, `required`, `string`, etc.
+
+`compute` and `related` do work for the most basic use-cases, but do not expect
+them to function reliably as they would on the actual server.
+
+.. note::
+    There are 4 default fields pre-defined for each created model: `id`, `display_name`,
+    `created_at` and `updated_at`. They match their server-side counterpart in their
+    behaviour (e.g. `id` is incremental and `display_name` has a `compute` function
+    similar to its server counterpart), and can be overridden if needed.
+
+Mock models: records
+--------------------
+
+Model records are generated based on each object contained in the `_records`
+special key *when the model is loaded*. They are validated based on the fields available
+on the current models; if a property does not match a field defined on the model,
+an error is thrown.
+
+.. important::
+    `_records` *cannot* be altered *after* the model has been loaded, i.e. after
+    the mock server has started. This key is only used to generate initial records.
+    If records should be added *after* model creation, do it either form the available
+    components in the UI, or through direct ORM calls on the mock server instance.
+
+Mock models: views
+------------------
+
+Since actual views need an `"ir.ui.view"` model to be declared, mock models
+use a simplified *mapping* to provide view arches.
+
+The `_view` special key is a dictionary, with its *keys* being view types, optionally
+accompanied by a view ID, and its *values* being the XML arch string representation.
+
+By default, view IDs are `false`, but can be specified explicitly with a comma-separated
+key combining the view type and its ID:
+
+.. code-block:: javascript
+
+    // Will simulate a list view with no ID (false).
+    ResPartner._views.list = /* xml */ `
+        <list>
+            <field name="display_name" />
+        </list>
+    `;
+
+    // Will simulate a form view with ID 418.
+    ResPartner._views["form,418"] = /* xml */ `
+        <form>
+            <field name="name" />
+            <field name="date" />
+        </form>
+    `;
+
+.. _mock-server/spawning:
+
+Spawning a mock server
+======================
+
+Just like in most cases, only one server can be active for a given test.
+
+As mentioned above, creating an `env` will automatically deploy a mock server.
+
+This means that all of these methods will *also* create a mock server, since
+they do create an `env`:
+
+- :ref:`makeMockEnv <web-test-helpers/environment>`;
+
+- :ref:`mountWithCleanup <web-test-helpers/components>` (calling :ref:`makeMockEnv <web-test-helpers/environment>`);
+
+- :ref:`mountView <web-test-helpers/views>` (calling :ref:`mountWithCleanup <web-test-helpers/components>`).
+
+However, some low-level features may require to spawn a mock server *without* an
+environment. For that purpose, a `makeMockServer` helper can be called separately
+to initiate a mock server.
+
+.. note::
+    `makeMockServer` should *only* be used by low-level features, such as testing
+    the `rpc` function without the environment. It is not meant to be used as a
+    means to retrieve the current mock server instance. For that purpose, refer to
+    :ref:`MockServer.current <mock-server/interacting>`.
+
+.. note::
+    It is to be noted that subsequent calls to `makeMockServer` after a mock server
+    has been started are simply ignored.
+
+.. _mock-server/interacting:
+
+Interacting with the server
+===========================
+
+While most of the server interactions are expected to be done directly or indirectly
+by production code spawned in the test case, it is sometimes meaningful to bypass
+the UI and call the mock server directly (e.g. to simulate that another user,
+somewhere else, somehow, has altered the database).
+
+This can be done by retrieving the `MockServer.current` static property containing
+the current mock server instance (only after initialization):
+
+.. code-block:: javascript
+
+    // Most common ORM methods are provided out of the box by server models,
+    // and are synchronous. Although, be careful that this will NOT trigger a
+    // UI re-render, and will ONLY affect the (fake) database.
+    const ids = MockServer.env["res.partner"].create([
+        { name: "foo" },
+        { name: "bar" },
+    ]);
+
+.. tip::
+    `MockServer.env` is just a shortcut to `MockServer.current.env`.
+
+.. _fetch: https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch
+.. _public-class-fields: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields
+.. _Request: https://developer.mozilla.org/en-US/docs/Web/API/Request
+.. _Response: https://developer.mozilla.org/en-US/docs/Web/API/Response
+.. _XMLHttpRequest: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
diff --git a/content/developer/reference/frontend/unit_testing/web_helpers.rst b/content/developer/reference/frontend/unit_testing/web_helpers.rst
new file mode 100644
index 0000000000..43df801d3a
--- /dev/null
+++ b/content/developer/reference/frontend/unit_testing/web_helpers.rst
@@ -0,0 +1,187 @@
+================
+Web test helpers
+================
+
+Overview
+========
+
+After the :doc:`"@odoo/hoot" <./hoot>` module, the second most-solicited module
+in test files should be `"@web/../tests/web_test_helpers"`.
+
+This module contains all the helpers that combine the low-level helpers provided
+by Hoot, with all the most common features that are used in tests in Odoo.
+
+These helpers are many, and this section of the documentation will only highlight
+the most common ones, and the way they interact with one another.
+
+For a full list of available helpers, you may refer to the `web_test_helpers file <{GITHUB_PATH}/addons/web/static/tests/web_test_helpers.js>`_.
+
+.. _web-test-helpers/environment:
+
+Mock environment
+================
+
+The `makeMockEnv` helper is the lowest helper that can spawn an `env`.
+
+It will take care of
+
+- creating the `env` object itself, pre-configured with all the required properties
+  for the proper functioning of web components, such as `getTemplate` or `translateFn`;
+
+- spawning a `MockServer` (if one did not exist already for that test);
+
+- starting all registered :doc:`services <../services>`, and awaiting until they are all ready;
+
+- initiating other features that are not tied to a service, such as the web `router`;
+
+- guaranteeing the teardown of all the features in its setup at the end of the test.
+
+This method is great for testing low-level features, such as :doc:`services <../services>` that are
+not tied to a Component_:
+
+.. code-block:: javascript
+
+    // Can be further configured, but is already packed with all the necessary stuff
+    const env = await makeMockEnv();
+
+    expect(env.isSmall).toBe(false);
+
+.. note::
+    Like :ref:`makeMockServer <mock-server/spawning>`, only one `env` can be active for a given test.
+    It is not necessary to call `makeMockEnv` manually to retrieve the current environment
+    instance; the `getMockEnv` helper can be called instead.
+
+.. example::
+
+    - `DateTime input tests <{GITHUB_PATH}/addons/web/static/tests/core/components/datetime/datetime_input.test.js>`_
+
+    - `Name service tests <{GITHUB_PATH}/addons/web/static/tests/core/name_service.test.js>`_
+
+.. _web-test-helpers/components:
+
+Mounting components
+===================
+
+Instantiating and appending `components <Component_>`_ to the DOM is meant to be easy,
+through the use of the `mountWithCleanup` helper. It will prepare an `env` internally
+(if one does not exist yet), which in turn also makes sure that a `MockServer` is
+running.
+
+It takes a `Component` class as its first argument, and an *optional* parameters
+second argument, used to specify `props` or a custom `target`:
+
+.. code-block:: javascript
+
+    await mountWithCleanup(Checkbox, {
+        props: {
+            value: false
+        },
+    });
+
+This helper will return the active `Component` instance.
+
+.. important::
+    It is generally *ill-advised* to retrieve the `Component` instance to directly
+    interact with it or to perform assertions on its internal variables. The only
+    "accepted" use cases are when the `Component` is displaying hard-to-retrieve information
+    in the DOM, such as graphs in a `canvas <https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API>`_.
+    For most cases, it is highly preferred to query derived information in the DOM.
+
+.. example::
+
+    - `Checkbox tests <{GITHUB_PATH}/addons/web/static/tests/core/checkbox.test.js>`_
+
+    - `Popover tests <{GITHUB_PATH}/addons/web/static/tests/core/popover/popover.test.js>`_
+
+    - `DateTimePicker tests <{GITHUB_PATH}/addons/web/static/tests/core/components/datetime/datetime_picker.test.js>`_
+
+.. _web-test-helpers/views:
+
+Mounting views
+==============
+
+Mounting a view is simply a matter of using :ref:`mountWithCleanup <web-test-helpers/components>`
+with the View_ component and the correct properties.
+
+For that purpose, web test helpers export a `mountView` helper, taking a parameters
+object determining the view `type`, `resModel`, and other optional properties such
+as an XML `arch`:
+
+.. code-block:: javascript
+
+    // Resolves when the view is fully ready
+    await mountView({
+        type: "list",
+        resModel: "res.partner",
+        arch: /* xml */ `
+            <list>
+                <field name="display_name" />
+            </list>
+        `,
+    });
+
+Like the previous helpers on top of which `mountView` is built, it will ensure that
+both an `env` and a `MockServer` are running for the current test.
+
+.. note::
+    Like :ref:`mountWithCleanup <web-test-helpers/components>`, it is *NOT*
+    recommended to retrieve the returned View_ component instance. It can however
+    be done, for cases like the `Graph view <{GITHUB_PATH}/addons/web/static/src/views/graph/graph_view.js>`_.
+
+.. example::
+
+    - `Calendar view tests <{GITHUB_PATH}/addons/web/static/tests/views/calendar/calendar_view.test.js>`_
+
+    - `Graph view tests <{GITHUB_PATH}/addons/web/static/tests/views/graph/graph_view.test.js>`_
+
+    - `Kanban view tests <{GITHUB_PATH}/addons/web/static/tests/views/kanban/kanban_view.test.js>`_
+
+Interacting with components
+===========================
+
+Hoot provides helpers to interact with the DOM (e.g. `click`, `press`, etc.). However,
+these helpers present 2 issues when interacting with more complex components:
+
+#. helpers try to interact instantly, while sometimes the element has yet to be
+   appended to the document (in an unknown amount of time);
+
+#. helpers only wait a single micro-task tick per dispatched event, while most
+   Owl-based UIs take at least a full animation frame to update.
+
+.. code-block:: javascript
+
+    // Edit record name
+    await click(".o_field_widget[name=name]");
+    await edit("Gaston Lagaffe");
+
+    // Potential error 1: button may not be in the DOM yet
+    await click(".btn:contains(Save)");
+
+    // Potential error 2: view is not yet updated
+    expect(".o_field_widget[name=name]").toHaveText("Gaston Lagaffe");
+
+With these constraints in mind, web test helpers provide the `contains` helper:
+
+.. code-block:: javascript
+
+    // Combines 'click' + 'edit' + 'animationFrame' calls
+    await contains(".o_field_widget[name=name]").edit("Gaston Lagaffe");
+    // Waits for (at least) a full animation frame after the click
+    await contains(".btn:contains(Save)").click();
+    expect(".o_field_widget[name=name]").toHaveText("Gaston Lagaffe");
+
+This approach, while seemingly drifting a bit further away from the concept of "unit
+testing", is still a nice and convenient way to test more complex units such as `views <View_>`_,
+the `WebClient <{GITHUB_PATH}/addons/web/static/src/webclient/webclient.js>`_, or
+interactions between couples of :doc:`services <../services>` and components.
+
+It should however not become the default for all interactions, as some of them still
+need to happen *precisely* within a given time frame, which is a concept completely
+ignored by `contains`.
+
+.. note::
+    Most helpers in Hoot are available as methods of a `contains` instance, with
+    (generally) the same shape and API.
+
+.. _Component: https://github.com/odoo/owl/blob/master/doc/reference/component.md
+.. _View: {GITHUB_PATH}/addons/web/static/src/views/view.js

From 6577fb71611701dc83c0cc2df5698eb40c12b8dc Mon Sep 17 00:00:00 2001
From: Julien Mougenot <jum@odoo.com>
Date: Thu, 9 Oct 2025 15:17:33 +0000
Subject: [PATCH 2/2] [FIX] web: remove/update old QUnit documentation

This commit replaces the outdated QUnit documentation with links to the
freshly written Hoot/web testing documentation.

X-original-commit: 33d70581131e5a7098aefe9ef101f7573422413f
---
 .../developer/reference/backend/testing.rst   | 251 +-----------------
 .../developer/reference/frontend/assets.rst   |   9 +-
 .../reference/frontend/unit_testing/hoot.rst  |   4 +-
 3 files changed, 12 insertions(+), 252 deletions(-)

diff --git a/content/developer/reference/backend/testing.rst b/content/developer/reference/backend/testing.rst
index d3458dc3de..10bf74372c 100644
--- a/content/developer/reference/backend/testing.rst
+++ b/content/developer/reference/backend/testing.rst
@@ -281,252 +281,17 @@ Testing JS code
 
 Testing a complex system is an important safeguard to prevent regressions and to
 guarantee that some basic functionality still works. Since Odoo has a non trivial
-codebase in Javascript, it is necessary to test it. In this section, we will
-discuss the practice of testing JS code in isolation: these tests stay in the
-browser, and are not supposed to reach the server.
+codebase in Javascript, it is necessary to test it.
 
-.. _reference/testing/qunit:
+See the :doc:`Unit testing <../frontend/unit_testing>` to learn about the
+various aspect of the front-end testing framework, or jump directly to one of the
+sub-sections:
 
-Qunit test suite
-----------------
+- :doc:`Hoot <../frontend/unit_testing/hoot>`
 
-The Odoo framework uses the QUnit_ library testing framework as a test runner.
-QUnit defines the concepts of *tests* and *modules* (a set of related tests),
-and gives us a web based interface to execute the tests.
+- :doc:`Web test helpers <../frontend/unit_testing/web_helpers>`
 
-For example, here is what a pyUtils test could look like:
-
-.. code-block:: javascript
-
-    QUnit.module('py_utils');
-
-    QUnit.test('simple arithmetic', function (assert) {
-        assert.expect(2);
-
-        var result = pyUtils.py_eval("1 + 2");
-        assert.strictEqual(result, 3, "should properly evaluate sum");
-        result = pyUtils.py_eval("42 % 5");
-        assert.strictEqual(result, 2, "should properly evaluate modulo operator");
-    });
-
-The main way to run the test suite is to have a running Odoo server, then
-navigate a web browser to ``/web/tests``.  The test suite will then be executed
-by the web browser Javascript engine.
-
-.. image:: testing/tests.png
-    :align: center
-
-The web UI has many useful features: it can run only some submodules, or
-filter tests that match a string. It can show every assertions, failed or passed,
-rerun specific tests, ...
-
-.. warning::
-
-    While the test suite is running, make sure that:
-
-    - your browser window is focused,
-    - it is not zoomed in/out. It needs to have exactly 100% zoom level.
-
-    If this is not the case, some tests will fail, without a proper explanation.
-
-Testing Infrastructure
-----------------------
-
-Here is a high level overview of the most important parts of the testing
-infrastructure:
-
-- there is an asset bundle named `web.qunit_suite`_.  This bundle contains
-  the main code (assets common + assets backend), some libraries, the QUnit test
-  runner and the test bundles listed below.
-
-- a bundle named `web.tests_assets`_ includes most of the assets and utils required
-  by the test suite: custom QUnit asserts, test helpers, lazy loaded assets, etc.
-
-- another asset bundle, `web.qunit_suite_tests`_, contains all the test scripts.
-  This is typically where the test files are added to the suite.
-
-- there is a `controller`_ in web, mapped to the route */web/tests*. This controller
-  simply renders the *web.qunit_suite* template.
-
-- to execute the tests, one can simply point its browser to the route */web/tests*.
-  In that case, the browser will download all assets, and QUnit will take over.
-
-- there is some code in `qunit_config.js`_ which logs in the console some
-  information when a test passes or fails.
-
-- we want the runbot to also run these tests, so there is a test (in `test_js.py`_)
-  which simply spawns a browser and points it to the *web/tests* url.  Note that
-  the browser_js method spawns a Chrome headless instance.
-
-
-Modularity and testing
-----------------------
-
-With the way Odoo is designed, any addon can modify the behaviour of other parts
-of the system.  For example, the *voip* addon can modify the *FieldPhone* widget
-to use extra features.  This is not really good from the perspective of the
-testing system, since this means that a test in the addon web will fail whenever
-the voip addon is installed (note that the runbot runs the tests with all addons
-installed).
-
-At the same time, our testing system is good, because it can detect whenever
-another module breaks some core functionality.  There is no complete solution to
-this issue.  For now, we solve this on a case by case basis.
-
-Usually, it is not a good idea to modify some other behaviour.  For our voip
-example, it is certainly cleaner to add a new *FieldVOIPPhone* widget and
-modify the few views that needs it.  This way, the *FieldPhone* widget is not
-impacted, and both can be tested.
-
-Adding a new test case
-----------------------
-
-Let us assume that we are maintaining an addon *my_addon*, and that we
-want to add a test for some javascript code (for example, some utility function
-myFunction, located in *my_addon.utils*). The process to add a new test case is
-the following:
-
-1. create a new file *my_addon/static/tests/utils_tests.js*. This file contains the basic code to
-   add a QUnit module *my_addon > utils*.
-
-    .. code-block:: javascript
-
-        odoo.define('my_addon.utils_tests', function (require) {
-        "use strict";
-
-        var utils = require('my_addon.utils');
-
-        QUnit.module('my_addon', {}, function () {
-
-            QUnit.module('utils');
-
-        });
-        });
-
-
-2. In *my_addon/assets.xml*, add the file to the main test assets:
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="utf-8"?>
-        <odoo>
-            <template id="qunit_suite_tests" name="my addon tests" inherit_id="web.qunit_suite_tests">
-                <xpath expr="//script[last()]" position="after">
-                    <script type="text/javascript" src="/my_addon/static/tests/utils_tests.js"/>
-                </xpath>
-            </template>
-        </odoo>
-
-3. Restart the server and update *my_addon*, or do it from the interface (to
-   make sure the new test file is loaded)
-
-4. Add a test case after the definition of the *utils* sub test suite:
-
-    .. code-block:: javascript
-
-        QUnit.test("some test case that we want to test", function (assert) {
-            assert.expect(1);
-
-            var result = utils.myFunction(someArgument);
-            assert.strictEqual(result, expectedResult);
-        });
-
-5. Visit */web/tests/* to make sure the test is executed
-
-Helper functions and specialized assertions
--------------------------------------------
-
-Without help, it is quite difficult to test some parts of Odoo. In particular,
-views are tricky, because they communicate with the server and may perform many
-rpcs, which needs to be mocked.  This is why we developed some specialized
-helper functions, located in `test_utils.js`_.
-
-- Mock test functions: these functions help setting up a test environment. The
-  most important use case is mocking the answers given by the Odoo server. These
-  functions use a `mock server`_. This is a javascript class that simulates
-  answers to the most common model methods: read, search_read, nameget, ...
-
-- DOM helpers: useful to simulate events/actions on some specific target. For
-  example, testUtils.dom.click performs a click on a target.  Note that it is
-  safer than doing it manually, because it also checks that the target exists,
-  and is visible.
-
-- create helpers: they are probably the most important functions exported by
-  `test_utils.js`_.  These helpers are useful to create a widget, with a mock
-  environment, and a lot of small detail to simulate as much as possible the
-  real conditions.  The most important is certainly `createView`_.
-
-- `qunit assertions`_: QUnit can be extended with specialized assertions. For
-  Odoo, we frequently test some DOM properties. This is why we made some
-  assertions to help with that.  For example, the *containsOnce* assertion takes
-  a widget/jQuery/HtmlElement and a selector, then checks if the target contains
-  exactly one match for the css selector.
-
-For example, with these helpers, here is what a simple form test could look like:
-
-.. code-block:: javascript
-
-    QUnit.test('simple group rendering', function (assert) {
-        assert.expect(1);
-
-        var form = testUtils.createView({
-            View: FormView,
-            model: 'partner',
-            data: this.data,
-            arch: '<form string="Partners">' +
-                    '<group>' +
-                        '<field name="foo"/>' +
-                    '</group>' +
-                '</form>',
-            res_id: 1,
-        });
-
-        assert.containsOnce(form, 'table.o_inner_group');
-
-        form.destroy();
-    });
-
-Notice the use of the testUtils.createView helper and of the containsOnce
-assertion.  Also, the form controller was properly destroyed at the end of
-the test.
-
-Best Practices
---------------
-
-In no particular order:
-
-- all test files should be added in *some_addon/static/tests/*
-- for bug fixes, make sure that the test fails without the bug fix, and passes
-  with it.  This ensures that it actually works.
-- try to have the minimal amount of code necessary for the test to work.
-- usually, two small tests are better than one large test.  A smaller test is
-  easier to understand and to fix.
-- always cleanup after a test.  For example, if your test instantiates a widget,
-  it should destroy it at the end.
-- no need to have full and complete code coverage.  But adding a few tests helps
-  a lot: it makes sure that your code is not completely broken, and whenever a
-  bug is fixed, it is really much easier to add a test to an existing test suite.
-- if you want to check some negative assertion (for example, that a HtmlElement
-  does not have a specific css class), then try to add the positive assertion in
-  the same test (for example, by doing an action that changes the state). This
-  will help avoid the test to become dead in the future (for example, if the css
-  class is changed).
-
-Tips
-----
-
-- running only one test: you can (temporarily!) change the *QUnit.test(...)*
-  definition into *QUnit.only(...)*.  This is useful to make sure that QUnit
-  only runs this specific test.
-- debug flag: most create utility functions have a debug mode (activated by the
-  debug: true parameter).  In that case, the target widget will be put in the DOM
-  instead of the hidden qunit specific fixture, and more information will be
-  logged. For example, all mocked network communications will be available in the
-  console.
-- when working on a failing test, it is common to add the debug flag, then
-  comment the end of the test (in particular, the destroy call).  With this, it
-  is possible to see the state of the widget directly, and even better, to
-  manipulate the widget by clicking/interacting with it.
+- :doc:`Mock server <../frontend/unit_testing/mock_server>`
 
 .. _reference/testing/integration-testing:
 
@@ -982,8 +747,6 @@ you can use the :meth:`~odoo.tests.BaseCase.assertQueryCount` method, integrated
 .. _qunit: https://qunitjs.com/
 .. _qunit_config.js: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/qunit_config.js#L49
 .. _web.tests_assets: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L594
-.. _web.qunit_suite: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L660
-.. _web.qunit_suite_tests: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/views/webclient_templates.xml#L680
 .. _controller: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/controllers/main.py#L637
 .. _test_js.py: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/tests/test_js.py#L13
 .. _test_utils.js: https://github.com/odoo/odoo/blob/51ee0c3cb59810449a60dae0b086b49b1ed6f946/addons/web/static/tests/helpers/test_utils.js
diff --git a/content/developer/reference/frontend/assets.rst b/content/developer/reference/frontend/assets.rst
index c4d912842d..7f28b412c4 100644
--- a/content/developer/reference/frontend/assets.rst
+++ b/content/developer/reference/frontend/assets.rst
@@ -75,8 +75,8 @@ like this:
             'web/static/src/js/webclient.js',
             'web/static/src/xml/webclient.xml',
         ],
-        'web.qunit_suite_tests': [
-            'web/static/src/js/webclient_tests.js',
+        'web.assets_unit_tests': [
+            'web/static/src/js/webclient.test.js',
         ],
     },
 
@@ -94,10 +94,7 @@ know:
 - `web.assets_frontend`: this bundle is about all that is specific to the public
   website: ecommerce, portal, forum, blog, ...
 
-- `web.qunit_suite_tests`: all javascript qunit testing code (tests, helpers, mocks)
-
-- `web.qunit_mobile_suite_tests`: mobile specific qunit testing code
-
+- `web.assets_unit_tests`: all javascript unit testing code (tests, helpers, mocks)
 
 Operations
 ----------
diff --git a/content/developer/reference/frontend/unit_testing/hoot.rst b/content/developer/reference/frontend/unit_testing/hoot.rst
index beb53450c0..8fb4a816fe 100644
--- a/content/developer/reference/frontend/unit_testing/hoot.rst
+++ b/content/developer/reference/frontend/unit_testing/hoot.rst
@@ -15,12 +15,12 @@ key features are:
 
 As such, it has been integrated as a :file:`lib/` in the Odoo codebase and exports 2 main modules:
 
-- :file:`@odoo/hoot-dom`: (can be used in production code) helpers to:
+- :file:`@odoo/hoot-dom`: (can be used in tours) helpers to:
 
     - **interact** with the DOM, such as :js:meth:`click` and :js:meth:`press`;
     - **query** elements from the DOM, such as :js:meth:`queryAll` and :js:meth:`waitFor`;
 
-- :file:`@odoo/hoot`: (only to be used in tests) all the test framework features:
+- :file:`@odoo/hoot`: (only to be used in unit tests) all the test framework features:
 
     - `test`, `describe` and `expect`
     - test hooks like `after` and `afterEach`