docs: sync changes from html-reporter repo (#94)

Author: shadowusr

docs/_partials/html-reporter-config-examples.mdx

@@ -1,3 +1,4 @@
+import Admonition from "@theme/Admonition";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
@@ -33,6 +34,17 @@ import TabItem from "@theme/TabItem";
     </TabItem>
 
     <TabItem value="Jest" label="Jest">
+        ```javascript title="jest.config.ts"
+        const config = {
+            // ...
+            reporters: [
+                'html-reporter/jest', // Connecting our reporter
+                'default' // Built in Jest reporter or any additional reporters you need (optional)
+            ],
+        };
+        ```
+
+        If you want to pass configuration options, you may do the following:
         ```javascript title="jest.config.ts"
         const config = {
             // ...
@@ -43,6 +55,8 @@ import TabItem from "@theme/TabItem";
             ],
         };
         ```
+
+        <Admonition type="warning">If you are using jest@27 or below, you need to use the following path: `html-reporter/build/jest`.</Admonition>
     </TabItem>
 
 </Tabs>

docs/html-reporter/html-reporter-api.mdx

@@ -17,10 +17,11 @@ Html-reporter adds an `htmlReporter` object to the `testplane` object with its o
 <tr><td>[extraItems](#extraitems)</td><td>Object</td><td>Additional elements to be added to the burger menu of the report.</td></tr>
 <tr><td>[imagesSaver](#imagessaver)</td><td>Object</td><td>Interface for saving images to the user's storage.</td></tr>
 <tr><td>[reportsSaver](#reportssaver)</td><td>Object</td><td>Interface for saving sqlite databases to the user's storage.</td></tr>
+<tr><td>[snapshotsSaver](#snapshotssaver)</td><td>Object</td><td>Interface for saving snapshots to the user's storage.</td></tr>
 <tr><td>[addExtraItem](#addextraitem)</td><td>Method</td><td>Adds an additional item to the burger menu of the report.</td></tr>
 <tr><td>[downloadDatabases](#downloaddatabases)</td><td>Method</td><td>Downloads all databases from the given files of the type _databaseUrls.json_.</td></tr>
 <tr><td>[mergeDatabases](#mergedatabases)</td><td>Method</td><td>Merges all given databases and saves the final report on the specified path.</td></tr>
-<tr><td>[getTestsTreeFromDatabase](#getteststreefromdatabase)</td><td>Method</td><td>Returns the test tree from the passed database.</td></tr>
+<tr><td>[getTestsTreeFromDatabase](#getteststreefromdatabase)</td><td>Method</td><td>Resolves the test tree from the passed database.</td></tr>
 
 </tbody>
 </table>
@@ -109,6 +110,42 @@ module.exports = (testplane, opts) => {
 };
 ```
 
+## snapshotsSaver
+
+Interface for saving DOM-snapshots to the user's storage.
+
+### Usage example
+
+```javascript
+const MyStorage = require("my-storage");
+const myStorage = new MyStorage();
+
+module.exports = (testplane, opts) => {
+    testplane.on(testplane.events.INIT, async () => {
+        testplane.htmlReporter.snapshotsSaver = {
+            /**
+             * Save snapshot to user storage.
+             * The function can be either asynchronous or synchronous.
+             * The function should return the path or URL to the saved snapshot.
+             * @property {String} localFilePath – the path to the snapshot on the file system
+             * @param {Object} options
+             * @param {String} options.destPath – the path to the snapshot in the html-report
+             * @param {String} options.reportDir - path to the html-report folder
+             * @returns {String} the path or URL to the snapshot
+             */
+            saveSnapshot: async (localFilePath, options) => {
+                const { destPath, reportDir } = options;
+                const snapshotUrl = await myStorage.save(localFilePath, destPath, reportDir);
+
+                // ...
+
+                return snapshotUrl;
+            },
+        };
+    });
+};
+```
+
 ## addExtraItem
 
 Adds an additional item to the burger menu of the report.
@@ -177,12 +214,12 @@ await testplane.htmlReporter.mergeDatabases(srcDbPaths, path);
 
 ## getTestsTreeFromDatabase
 
-Returns the test tree from the passed database.
+Resolves the test tree from the passed database.
 
 ### Example of a call {#get_tests_tree_from_database_call_example}
 
 ```javascript
-const dbTree = testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
+const dbTree = await testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
 ```
 
 ### Call parameters {#get_tests_tree_from_database_call_params}
@@ -192,8 +229,8 @@ The function takes one argument—the path to the database with the result of th
 ### Usage example {#get_tests_tree_from_database_usage_example}
 
 ```javascript
-function getSuccessTestRunIds({ testplane, mergedDbPath }) {
-    const dbTree = testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
+async function getSuccessTestRunIds({ testplane, mergedDbPath }) {
+    const dbTree = await testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
 
     const successTestRunIds = [];
 

docs/html-reporter/html-reporter-commands.mdx

@@ -55,21 +55,38 @@ It creates a new html-report in the destination folder with data from all passed
 The `merge-reports` command supports the following required option:
 
 <table>
-<thead>
-<tr><td>**Option**</td><td>**Description**</td></tr>
-</thead>
-<tbody>
-<tr><td>-d, --destination &lt;folder></td><td>The path to the folder where you want to save the final report.</td></tr>
-
-</tbody>
+    <thead>
+        <tr>
+            <td>**Option**</td>
+            <td>**Description**</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>-d, --destination &lt;folder></td>
+            <td>The path to the folder where you want to save the final report.</td>
+        </tr>
+        <tr>
+            <td>-h, --header &lt;header></td>
+            <td>Http header for databaseUrls.json files from source paths.</td>
+        </tr>
+    </tbody>
 </table>
 
 Usage example:
 
 ```bash
-npx html-reporter merge-reports report-dir/ path-to-database.db path-to-databaseUrls.json -d dest-report
+npx html-reporter merge-reports report-dir/ path-to-database.db path-to-databaseUrls.json -d dest-report -h foo=bar
 ```
 
+Http headers can also be send using the environment variable — `html_reporter_headers` (has a higher priority than the cli option `--header'). Example:
+
+```bash
+html_reporter_headers='{"foo":"bar"}' npx hermione merge-reports path-to-database.db path-to-databaseUrls.json -d dest-report -h baz=qux
+```
+
+In this call, the `path-to-databaseUrls.json` will be requested with headers: `{foo: 'bar', baz: 'qux'}`.
+
 ## remove-unused-screens
 
 <Admonition type="info" title="Command availability">

docs/html-reporter/html-reporter-events.mdx

@@ -28,7 +28,7 @@ testplane.htmlReporter.on(testplane.htmlReporter.events.DATABASE_CREATED, db =>
 
 #### Handler parameters {#database_created_handler_params}
 
-A database instance is passed to the event handler.
+A [sql.js](https://www.npmjs.com/package/sql.js) database instance is passed to the event handler.
 
 ### Usage example {#database_created_example}
 

docs/html-reporter/html-reporter-setup.mdx

@@ -4,60 +4,14 @@ sidebar_position: 2
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
-
 import Admonition from "@theme/Admonition";
+import ConfigExamples from "/docs/_partials/html-reporter-config-examples.mdx";
 
 # Configuration
 
 ## Config Examples {#setup}
 
-<Tabs>
-<TabItem value="Testplane" label="Testplane">
-    ```javascript title="testplane.config.ts"
-    export = {
-        // ...
-        plugins: {
-            'html-reporter/testplane': {
-                enabled: true,
-                path: 'html-report',
-            },
-        },
-    };
-    ```
-
-</TabItem>
-
-<TabItem value="Playwright" label="Playwright">
-    ```javascript title="playwright.config.ts"
-     // playwright.config.ts
-    export default defineConfig({
-        // ...
-        reporter: [
-            ['html-reporter/playwright', {
-                enabled: true,
-                defaultView: 'failed',
-                path: 'html-report',
-            }],
-        ],
-    });
-    ```
-
-</TabItem>
-
-<TabItem value="Jest" label="Jest">
-    ```javascript title="jest.config.ts"
-     const config = {
-        // ...
-        reporters: [
-            ['html-reporter/jest', {
-                path: 'html-report',
-            }]
-        ],
-    };
-    ```
-</TabItem>
-
-</Tabs>
+<ConfigExamples />
 
 ## Configuration Reference {#setup_description}
 

i18n/ru/docusaurus-plugin-content-docs/current/_partials/html-reporter-config-examples.mdx

@@ -0,0 +1,62 @@
+import Admonition from "@theme/Admonition";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+<Tabs>
+    <TabItem value="Testplane" label="Testplane">
+        ```javascript title="testplane.config.ts"
+        export = {
+            // ...
+            plugins: {
+                'html-reporter/testplane': {
+                    enabled: true,
+                    path: 'html-report',
+                },
+            },
+        };
+        ```
+    </TabItem>
+
+    <TabItem value="Playwright" label="Playwright">
+        ```javascript title="playwright.config.ts"
+        // playwright.config.ts
+        export default defineConfig({
+            // ...
+            reporter: [
+                ['html-reporter/playwright', {
+                    enabled: true,
+                    defaultView: 'failed',
+                    path: 'html-report',
+                }],
+            ],
+        });
+        ```
+    </TabItem>
+
+    <TabItem value="Jest" label="Jest">
+        ```javascript title="jest.config.ts"
+        const config = {
+            // ...
+            reporters: [
+                'html-reporter/jest', // Подключаем наш репортер
+                'default' // Встроенный репортер Jest или любые другие необходимые (опционально)
+            ],
+        };
+        ```
+
+        Если нужно передать параметры конфигурации, можно сделать так:
+        ```javascript title="jest.config.ts"
+        const config = {
+            // ...
+            reporters: [
+                ['html-reporter/jest', {
+                    path: 'html-report',
+                }]
+            ],
+        };
+        ```
+
+        <Admonition type="warning">Если вы используете jest@27 или ниже, нужно указать следующий путь: `html-reporter/build/jest`.</Admonition>
+    </TabItem>
+
+</Tabs>

i18n/ru/docusaurus-plugin-content-docs/current/html-reporter/html-reporter-api.mdx

@@ -17,10 +17,11 @@ Html-reporter добавляет к объекту `testplane` объект `htm
 <tr><td>[extraItems](#extraitems)</td><td>Object</td><td>Дополнительные элементы, которые будут добавлены в бургер-меню отчета.</td></tr>
 <tr><td>[imagesSaver](#imagessaver)</td><td>Object</td><td>Интерфейс для сохранения изображений в хранилище пользователя.</td></tr>
 <tr><td>[reportsSaver](#reportssaver)</td><td>Object</td><td>Интерфейс для сохранения sqlite баз данных в хранилище пользователя.</td></tr>
+<tr><td>[snapshotsSaver](#snapshotssaver)</td><td>Object</td><td>Интерфейс для сохранения DOM-снапшотов в хранилище пользователя.</td></tr>
 <tr><td>[addExtraItem](#addextraitem)</td><td>Method</td><td>Добавляет дополнительный пункт в бургер-меню отчета.</td></tr>
 <tr><td>[downloadDatabases](#downloaddatabases)</td><td>Method</td><td>Скачивает все базы данных из переданных файлов типа _databaseUrls.json_.</td></tr>
 <tr><td>[mergeDatabases](#mergedatabases)</td><td>Method</td><td>Объединяет все переданные базы данных и сохраняет итоговый отчет по заданному пути.</td></tr>
-<tr><td>[getTestsTreeFromDatabase](#getteststreefromdatabase)</td><td>Method</td><td>Возвращает дерево тестов из переданной базы данных.</td></tr>
+<tr><td>[getTestsTreeFromDatabase](#getteststreefromdatabase)</td><td>Method</td><td>Асинхронно возвращает дерево тестов из переданной базы данных.</td></tr>
 
 </tbody>
 </table>
@@ -109,6 +110,42 @@ module.exports = (testplane, opts) => {
 };
 ```
 
+## snapshotsSaver
+
+Интерфейс для сохранения DOM-снапшотов в хранилище пользователя.
+
+### Пример использования {#snapshots_saver_usage_example}
+
+```javascript
+const MyStorage = require("my-storage");
+const myStorage = new MyStorage();
+
+module.exports = (testplane, opts) => {
+    testplane.on(testplane.events.INIT, async () => {
+        testplane.htmlReporter.snapshotsSaver = {
+            /**
+             * Сохранить снапшот в пользовательском хранилище.
+             * Функция может быть как асинхронной, так и синхронной.
+             * Функция должна возвращать путь или URL к сохраненному снапшоту.
+             * @property {String} localFilePath – путь к снапшоту на файловой системе
+             * @param {Object} options
+             * @param {String} options.destPath – путь к снапшоту в html-отчете
+             * @param {String} options.reportDir - путь к папке html-отчета
+             * @returns {String} путь или URL к снапшоту
+             */
+            saveSnapshot: async (localFilePath, options) => {
+                const { destPath, reportDir } = options;
+                const snapshotUrl = await myStorage.save(localFilePath, destPath, reportDir);
+
+                // ...
+
+                return snapshotUrl;
+            },
+        };
+    });
+};
+```
+
 ## addExtraItem
 
 Добавляет дополнительный пункт в виде ссылки в бургер-меню html-отчета.
@@ -177,12 +214,12 @@ await testplane.htmlReporter.mergeDatabases(srcDbPaths, path);
 
 ## getTestsTreeFromDatabase
 
-Возвращает дерево тестов из переданной базы данных.
+Асинхронно возвращает дерево тестов из переданной базы данных.
 
 ### Пример вызова {#get_tests_tree_from_database_call_example}
 
 ```javascript
-const dbTree = testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
+const dbTree = await testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
 ```
 
 ### Параметры вызова {#get_tests_tree_from_database_call_params}
@@ -192,8 +229,8 @@ const dbTree = testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
 ### Пример использования {#get_tests_tree_from_database_usage_example}
 
 ```javascript
-function getSuccessTestRunIds({ testplane, mergedDbPath }) {
-    const dbTree = testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
+async function getSuccessTestRunIds({ testplane, mergedDbPath }) {
+    const dbTree = await testplane.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
 
     const successTestRunIds = [];