Skip to content

Commit 40e9cb1

Browse files
shadowusrshadowusr
authored
docs: move docs to testplane.io (#728)
* docs: move docs to testplane.io * docs: move jest docs to website
1 parent 82c070f commit 40e9cb1

17 files changed

+28
-2550
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,8 @@ One link is worth a thousand words, so [here it is](https://storage.yandexcloud.
142142
## Docs
143143
144144
See full documentation in various languages here:
145-
* [English](./docs/en/html-reporter.md)
146-
* [Русский](./docs/ru/html-reporter.md)
145+
* [English](https://testplane.io/docs/v8/html-reporter/overview/)
146+
* [Русский](https://testplane.io/ru/docs/v8/html-reporter/overview/)
147147
148148
## Contributing
149149

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

Lines changed: 1 addition & 233 deletions
Original file line numberDiff line numberDiff line change
@@ -1,235 +1,3 @@
11
# API
22

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

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

Lines changed: 1 addition & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,3 @@
11
# Commands
22

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 options:
87-
88-
| **Option** | **Description** |
89-
| --------- | ------------ |
90-
| -d, --destination <folder> | The path to the folder where you want to save the final report. |
91-
| -h, --header <header> | Http header for databaseUrls.json files from source paths. |
92-
93-
Usage example:
94-
95-
```bash
96-
npx hermione merge-reports path-to-database.db path-to-databaseUrls.json -d dest-report -h foo=bar
97-
```
98-
99-
Http headers can also be send using the environment variable - `html_reporter_headers` (has a higher priority than the cli option `--header'). Example:
100-
101-
```bash
102-
html_reporter_headers='{"foo":"bar"}' npx hermione merge-reports path-to-database.db path-to-databaseUrls.json -d dest-report -h baz=qux
103-
```
104-
105-
As a result, the `path-to-databaseUrls.json` will be requested with headers: `{foo: 'bar', baz: 'qux'}`.
3+
- [Docs are available on testplane.io](https://testplane.io/docs/v8/html-reporter/html-reporter-commands/)

0 commit comments

Comments
 (0)