Skip to content

Commit ff78922

Browse files
author
Rashid Ksirov
committed
docs: rewrite documentation
1 parent a27c876 commit ff78922

15 files changed

+2342
-681
lines changed

‎README.md‎

Lines changed: 4 additions & 681 deletions
Large diffs are not rendered by default.

‎docs/en/html-reporter-api.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# API
2+
3+
## Overview
4+
5+
Html-reporter adds an `htmlReporter` object to the `hermione` object with its own API.
6+
7+
| **Name** | **Type** | **Descriptiion** |
8+
| -------- | -------- | ---------------- |
9+
| [events](#events) | Object | A list of events to subscribe to. |
10+
| [extraItems](#extraitems) | Object | Additional elements to be added to the burger menu of the report. |
11+
| [imagesSaver](#imagessaver) | Object | Interface for saving images to the user's storage. |
12+
| [reportsSaver](#reportssaver) | Object | Interface for saving sqlite databases to the user's storage. |
13+
| [addExtraItem](#addextraitem) | Method | Adds an additional item to the burger menu of the report. |
14+
| [downloadDatabases](#downloaddatabases) | Method | Downloads all databases from the given files of the type _databaseUrls.json_. |
15+
| [mergeDatabases](#mergedatabases) | Method | Merges all given databases and saves the final report on the specified path. |
16+
| [getTestsTreeFromDatabase](#getteststreefromdatabase) | Method | Returns the test tree from the passed database. |
17+
18+
## events
19+
20+
A list of events to subscribe to.
21+
22+
For more information, see the section "[Events](./html-reporter-events.md)".
23+
24+
## extraItems
25+
26+
Additional elements to be added to the burger menu of the report.
27+
28+
To add elements, use the [addExtraItem](#addextraitem) method.
29+
30+
## imagesSaver
31+
32+
Interface for saving images to the user's storage.
33+
34+
### Usage example
35+
36+
```javascript
37+
const MyStorage = require('my-storage');
38+
const myStorage = new MyStorage();
39+
40+
module.exports = (hermione, opts) => {
41+
hermione.on(hermione.events.INIT, async () => {
42+
hermione.htmlReporter.imagesSaver = {
43+
/**
44+
* Save the image to a custom storage.
45+
* The function can be either asynchronous or synchronous.
46+
* The function should return the path or URL to the saved image.
47+
* @property {String} localFilePath – the path to the image on the file system
48+
* @param {Object} options
49+
* @param {String} options.destPath – the path to the image in the html-report
50+
* @param {String} options.reportDir - path to the html-report folder
51+
* @returns {String} the path or URL to the image
52+
*/
53+
saveImg: async (localFilePath, options) => {
54+
const { destPath, reportDir } = options;
55+
const imageUrl = await myStorage.save(localFilePath, destPath, reportDir);
56+
57+
// ...
58+
59+
return imageUrl;
60+
}
61+
}
62+
});
63+
};
64+
```
65+
66+
## reportsSaver
67+
68+
Interface for saving sqlite databases to the user's storage.
69+
70+
### Usage example
71+
72+
```javascript
73+
const MyStorage = require('my-storage');
74+
const myStorage = new MyStorage();
75+
76+
module.exports = (hermione, opts) => {
77+
hermione.on(hermione.events.INIT, async () => {
78+
hermione.htmlReporter.reportsSaver = {
79+
/**
80+
* Save sqlite database to user storage.
81+
* The function can be either asynchronous or synchronous.
82+
* The function should return the path or URL to the saved sqlite database.
83+
* @property {String} localFilePath – the path to the sqlite database on the file system
84+
* @param {Object} options
85+
* @param {String} options.destPath – the path to the sqlite database in the html-report
86+
* @param {String} options.reportDir - path to the html-report folder
87+
* @returns {String} the path or URL to the sqlite database
88+
*/
89+
saveReportData: async (localFilePath, options) => {
90+
const { destPath, reportDir } = options;
91+
const dbUrl = await myStorage.save(localFilePath, destPath, reportDir);
92+
93+
// ...
94+
95+
return dbUrl;
96+
}
97+
}
98+
});
99+
};
100+
```
101+
102+
## addExtraItem
103+
104+
Adds an additional item to the burger menu of the report.
105+
106+
### Example of a call
107+
108+
```javascript
109+
hermione.htmlReporter.addExtraItem(caption, url);
110+
```
111+
112+
### Call parameters
113+
114+
All parameters are required.
115+
116+
| **Parameter name** | **Type** | **Description** |
117+
| ----------------------- | -------- | --------------- |
118+
| caption | String | The name of the item to add to the burger menu. |
119+
| url | String | The URL to which the menu item to be added will link. |
120+
121+
## downloadDatabases
122+
123+
Downloads all databases from the given files of the type `databaseUrls.json`.
124+
125+
### Example of a call
126+
127+
```javascript
128+
const dbPaths = await hermione.htmlReporter.downloadDatabases(
129+
['.\databaseUrls.json'], { pluginConfig }
130+
);
131+
```
132+
133+
### Call parameters
134+
135+
The function takes 2 arguments—a list of paths to the files `databaseUrls.json` in the form of an array of strings and an object with the key `pluginConfig`, in the value of which the plugin config is stored.
136+
137+
The function returns a list of paths to saved databases.
138+
139+
## mergeDatabases
140+
141+
Merges all given databases and saves the final report on the specified path.
142+
143+
### Example of a call
144+
145+
```javascript
146+
await hermione.htmlReporter.mergeDatabases(srcDbPaths, path);
147+
```
148+
149+
### Call parameters
150+
151+
| **Parameter name** | **Type** | **Description** |
152+
| ----------------------- | -------- | --------------- |
153+
| srcDbPaths | String[] | Paths to databases. |
154+
| path | String | The path where the resulting database will be saved. |
155+
156+
## getTestsTreeFromDatabase
157+
158+
Returns the test tree from the passed database.
159+
160+
### Example of a call
161+
162+
```javascript
163+
const dbTree = hermione.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
164+
```
165+
166+
### Call parameters
167+
168+
The function takes one argument—the path to the database with the result of the tests run.
169+
170+
### Usage example
171+
172+
```javascript
173+
function getSuccessTestRunIds({ hermione, mergedDbPath }) {
174+
const dbTree = hermione.htmlReporter.getTestsTreeFromDatabase(mergedDbPath);
175+
176+
const successTestRunIds = [];
177+
178+
for (const browserId of dbTree.browsers.allIds) {
179+
const browser = dbTree.browsers.byId[browserId];
180+
const lastResultId = _.last(browser.resultIds);
181+
const lastResult = lastResultId && dbTree.results.byId[lastResultId];
182+
183+
if (!lastResult || lastResult.status !== SUCCESS) {
184+
continue;
185+
}
186+
187+
const testRunId = new URL(lastResult.suiteUrl).searchParams.get("testRunId");
188+
189+
if (!testRunId) {
190+
continue;
191+
}
192+
193+
successTestRunIds.push(testRunId);
194+
}
195+
196+
return successTestRunIds;
197+
}
198+
```

‎docs/en/html-reporter-commands.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Commands
2+
3+
## Overview
4+
5+
The `html-reporter` plugin adds the following commands to Hermione:
6+
* [gui](#gui)—to run hermione in GUI mode;
7+
* [remove-unused-screens](#remove-unused-screens)—to remove reference screenshots that are not used in tests;
8+
* [merge-reports](#merge-reports)—to merge Hermione's separate reports into one general report.
9+
10+
## gui
11+
12+
Use the `gui` command to launch Hermione in GUI mode.
13+
14+
GUI mode allows you to:
15+
* run tests interactively;
16+
* update screenshots—visually viewing them and taking only the necessary diffs;
17+
* reuse reports from CI;
18+
* filter the results of the run by errors, keys from meta, etc.
19+
20+
### Usage
21+
22+
```bash
23+
npx hermione gui
24+
```
25+
26+
## remove-unused-screens
27+
28+
Use the `remove-unused-screens` command to remove the reference screenshots that are not used in tests.
29+
30+
### How does it work?
31+
32+
First, the command looks for screenshots for which there are no tests on the file system.
33+
34+
Next, the command searches for screenshots that were not used in successful testing (the test result is taken from the SQLite database). To do this, the html-report must exist on the file system and contain the results of the tests run. This means that you must run the tests locally or download the report from CI before running the `remove-unused-screens` command.
35+
36+
### Usage
37+
38+
The `remove-unused-screens` command supports several options:
39+
40+
| **Option** | **Description** |
41+
| ---------- | --------------- |
42+
| -p, --pattern <pattern> | A pattern for finding screenshots on the file system. |
43+
| --skip-questions | Do not ask questions during execution (use default values). |
44+
| -h, --help | Output the reference information on the command to the terminal. |
45+
46+
#### Usage examples
47+
48+
Specifying the folder in which to search for unused screenshots:
49+
50+
```bash
51+
npx hermione remove-unused-screens -p 'hermione-screens-folder'
52+
```
53+
54+
Setting the pattern by which to search for screenshots:
55+
56+
```bash
57+
npx hermione remove-unused-screens -p 'screens/**/*.png'
58+
```
59+
60+
Setting several patterns by which to search for screenshots:
61+
62+
```bash
63+
npx hermione remove-unused-screens -p 'screens/**/chrome/*.png' -p 'screens/**/firefox/*.png'
64+
```
65+
66+
Specifying the folder in which to search for unused screenshots and setting _do-not-ask-questions_ option:
67+
68+
```bash
69+
npx hermione remove-unused-screens -p 'hermione-screens-folder' --skip-questions
70+
```
71+
72+
Getting the reference information about the command:
73+
74+
```bash
75+
npx hermione remove-unused-screens --help
76+
```
77+
78+
## merge-reports
79+
80+
Use the `merge-reports` command to merge Hermione's separate reports into one general report.
81+
82+
The command accepts paths to database files or to `databaseUrls.json` files from other html-reports. It creates a new html-report in the destination folder with a single file `databaseUrls.json`, which will contain a link to the database file or to the files `databaseUrls.json` from the input parameters. Database files are not copied to the destination folder at the same time.
83+
84+
### Usage
85+
86+
The `merge-reports` command supports the following required option:
87+
88+
| **Option** | **Description** |
89+
| --------- | ------------ |
90+
| -d, --destination <folder> | The path to the folder where you want to save the final report. |
91+
92+
Usage example:
93+
94+
```bash
95+
npx hermione merge-reports path-to-database.db path-to-databaseUrls.json -d dest-report
96+
```

‎docs/en/html-reporter-custom-gui.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Customizing GUI
2+
3+
## Overview
4+
5+
:warning: _This method of GUI customization is outdated. It is recommended to use [report plugins](./html-reporter-plugins.md) instead._
6+
7+
Use the `customGui` option in the `html-reporter` plugin config to add custom controls for GUI mode.
8+
9+
For controls, their type (button or radio button), labels and values, as well as initialization functions and the main click action are set. The controls should be divided into separate sections depending on their purpose. At least one section must be specified.
10+
11+
By default, the value of the `customGui` option is `{}`.
12+
13+
## Setup
14+
15+
The `customGui` option requires an object of the following format for its value:
16+
17+
```javascript
18+
customGui: {
19+
'<section name>': [
20+
{
21+
type: '<type of control>', // 'button' or 'radiobutton'
22+
controls: [
23+
{
24+
label: '<label on the control>',
25+
value: '<value of the control>'
26+
},
27+
28+
// other controls...
29+
],
30+
initialize: async ({ hermione, ctx }) => {
31+
// initialization code
32+
// the return value will be ignored
33+
},
34+
action: async ({ hermione, ctx, control }) => {
35+
// action code
36+
// the return value will be ignored
37+
}
38+
},
39+
40+
// other groups of controls...
41+
],
42+
43+
// other sections...
44+
}
45+
```
46+
47+
### Description of configuration parameters
48+
49+
| **Parameter** | **Type** | **Description** |
50+
| ------------- | -------- | --------------- |
51+
| type | String | Required parameter. The type of controls. Available values: _'button'_ and _'radiobutton'_. |
52+
| controls | Array | An array of objects, each of which describes a control. The object must consist of two keys: _label_ and _value_, which specify the label on the control and its value. |
53+
| initialize | Function | Optional parameter. Asynchronous function that will be executed on the server side when Hermione starts in GUI mode. An object of the form _{ hermione, ctx }_ will be passed to the function, where _hermione_ is an instance of hermione, and _ctx_ is an object describing a group of elements for which the initialization function is called. |
54+
| action | Function | Required parameter. Asynchronous function that will be executed on the server side when the user clicks on the control. An object of the form _{ hermione, ctx, control }_ will be passed to the function, where _hermione_ is an instance of hermione, _ctx_ is an object describing a group of elements for which the _action_ function is called, and _control_ is a link to the control that the user clicked on. |
55+
56+
## Usage example
57+
58+
Adding radio buttons to change the base URL in GUI mode:
59+
60+
```javascript
61+
customGui: {
62+
'some-meaningful-name-of-section': [
63+
{
64+
type: 'radiobutton',
65+
controls: [
66+
{
67+
label: 'Dev',
68+
value: 'http://localhost/development/'
69+
},
70+
{
71+
label: 'Prod',
72+
value: 'http://localhost/production/'
73+
}
74+
],
75+
initialize: async ({ hermione, ctx }) => {
76+
const { config } = hermione;
77+
const browserIds = config.getBrowserIds();
78+
79+
if (browserIds.length) {
80+
const { baseUrl } = config.forBrowser(browserIds[0]);
81+
82+
ctx.controls.forEach((control) => {
83+
control.active = (baseUrl === control.value);
84+
});
85+
}
86+
},
87+
action: async ({ hermione, ctx, control }) => {
88+
const { config } = hermione;
89+
90+
config
91+
.getBrowserIds()
92+
.forEach((browserId) => {
93+
config.forBrowser(browserId).baseUrl = control.value;
94+
});
95+
}
96+
}
97+
]
98+
}
99+
```

0 commit comments

Comments
 (0)