Skip to content

Commit 9743ff6

Browse files
noomorphnoomorph
authored
docs(artifacts): info on the object configuration (wix#1998)
* Update APIRef.Artifacts.md * Update APIRef.Artifacts.md * Update APIRef.Artifacts.md
1 parent 62d3501 commit 9743ff6

File tree

1 file changed

+104
-2
lines changed

1 file changed

+104
-2
lines changed

‎docs/APIRef.Artifacts.md

Lines changed: 104 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,9 @@ Artifacts are disabled by default. Two things are required to enable them:
99
1. **Call `detox.beforeEach` and `detox.afterEach` before/after each test**:
1010
In order for artifacts to work, you have to call `detox.beforeEach(testSummary)` / `detox.afterEach(testSummary)` before / after each test. Their respective signatures are described in [detox object](APIRef.DetoxObjectAPI.md) documentation. As the interface (typing) of `testSummary` may change over the time, and in cases with some test runners it is not trivial to implement test title and status extraction (like with Jest), you are encouraged to use Detox adapter functions like in these examples: [mocha](/examples/demo-react-native/e2e/init.js), [jest](/examples/demo-react-native-jest/e2e/init.js).
1111

12-
2. Specify via launch arguments which types of artifacts you want to record:
12+
2. Specify via launch arguments or a configuration object what artifacts you want to record.
13+
14+
### Launch arguments
1315

1416
* To record `.log` files, add `--record-logs all` (or `--record-logs failing`, if you want to keep logs only for failing tests).
1517
* To record `.mp4` test run videos, add `--record-videos all` (or `--record-videos failing`, if you want to keep video recordings only for failing tests).
@@ -18,13 +20,113 @@ Artifacts are disabled by default. Two things are required to enable them:
1820
Alternatively, you might leverage the [device.takeScreenshot()](APIRef.DeviceObjectAPI.md#devicetakescreenshotname) API for manual control.
1921

2022
* To change artifacts root directory location (by default it is `./artifacts`), add `--artifacts-location <path>`.
21-
**NOTE:** There is a slightly obscure convention. If you want to create automatically a subdirectory with timestamp and configuration name (to avoid file overwrites upon consquent re-runs), specify a path to directory that does not end with a slash. Otherwise, if you want to put artifacts straight to the specified directory (in a case where you make a single run only, e.g. on CI), add a slash (or a backslash) to the end.
23+
**NOTE:** <a id="slash-convention">There</a> is a slightly obscure convention. If you want to create automatically a subdirectory with timestamp and configuration name (to avoid file overwrites upon consquent re-runs), specify a path to directory that does not end with a slash. Otherwise, if you want to put artifacts straight to the specified directory (in a case where you make a single run only, e.g. on CI), add a slash (or a backslash) to the end.
2224

2325
```sh
2426
detox test --artifacts-location /tmp/detox_artifacts # will also append /android.emu.release.2018-06-14 08:54:11Z
2527
detox test --artifacts-location /tmp/detox_artifacts/ # won't append anything, hereby treating it as a root
2628
```
2729

30+
### Configuration object
31+
32+
Detox artifacts can be configured in a more advanced way with the `artifacts` configuration in `package.json`:
33+
34+
```json
35+
{
36+
"detox": {
37+
"artifacts": {},
38+
"configurations": {
39+
"some.device": {
40+
"artifacts": {},
41+
},
42+
},
43+
}
44+
}
45+
```
46+
47+
**NOTE:** Detox merges artifact configurations from `package.json`, and the per-device artifacts configuration has a higher priority over the general one.
48+
49+
The `artifacts` object has the following properties:
50+
51+
| Property | Example values | Default value | Description |
52+
|-------------|---------------------------------|---------------|-------------|
53+
| rootDir | `".artifacts/"` | `./artifacts` | A directory, where all the recorded artifacts will be placed in. Please note that there is a trailing slash convention [described above](#slash-convention). |
54+
| pathBuilder | `"./e2e/config/pathbuilder.js"` | `undefined` | Path to a module that implements `PathBuilder` interface[<sup>\[a\]</sup>](#pathBuilder) |
55+
| plugins | `{ ... }` | ... see below | ... see below |
56+
57+
<a id=pathBuilder><sup>a</sup> PathBuilder</a> should be an object with a method `buildPathForTestArtifact` or a class. The `buildPathForTestArtifact` method has a signature: `(artifactName: string, testSummary?: { title: string; fullName: string; status: 'running' | 'passed' | 'failed' }) => string`, where it accepts a suggested artifact name (e.g., `testDone.png`, `device.log`), a current test summary with its name and status, and it is expected to return a full path to the custom artifact location. If it is a class, its constructor also accepts `{ rootDir }` configuration object. Search for `ArtifactPathBuilder.js` in Detox source code for a technical reference.
58+
59+
The further subsections describe the `plugins` object structure.
60+
61+
#### Screenshot plugin
62+
63+
Below is a default screenshot plugin object configuration, which is loaded implicitly and corresponds to the `manual` preset:
64+
65+
```json
66+
{
67+
"plugins": {
68+
"screenshot": {
69+
"enabled": true,
70+
"shouldTakeAutomaticSnapshots": false,
71+
"keepOnlyFailedTestsArtifacts": false,
72+
"takeWhen": {
73+
"testStart": true,
74+
"testDone": true,
75+
"appNotReady": true,
76+
},
77+
}
78+
}
79+
}
80+
```
81+
82+
The other string presets override the following properties compared to the default configuration:
83+
84+
* `none` => `{ enabled: false }`.
85+
* `failing` => `{ shouldTakeAutomaticSnapshots: true, keepOnlyFailedTestsArtifacts: true }`.
86+
* `all` => `{ shouldTakeAutomaticSnapshots: true, keepOnlyFailedTestsArtifacts: true }`
87+
88+
The invidual property behavior is the following:
89+
90+
* If `enabled` is _false_, then the screenshots will never be saved to the artifacts folder.
91+
* If `shouldTakeAutomaticSnapshots` is _false_, then no one of the events described in `takeWhen` object is going to trigger a screenshot.
92+
* If `keepOnlyFailedTestsArtifacts` is _true_, then only screenshots from a failed test will be saved to the artifacts folder.
93+
* If `takeWhen` is _undefined_, it is going to have the default value described above (all props are true).
94+
* If `takeWhen` is set to be an empty object `{}`, that is equivalent to:
95+
96+
```json
97+
{
98+
"testStart": false,
99+
"testDone": false,
100+
"appNotReady": true,
101+
}
102+
```
103+
104+
Hence, for example, if you wish to enable only `testDone` screenshots and leave taking `appNotReady` screenshots as-is, you have to pass:
105+
106+
```json
107+
{
108+
"artifacts": {
109+
"plugins": {
110+
"screenshot": {
111+
"takeWhen": { "testDone": true }
112+
}
113+
}
114+
}
115+
}
116+
```
117+
118+
#### Video plugin
119+
120+
To be done. See meanwhile the example in [APIRef.Configuration.md#artifacts-configuration](APIRef.Configuration.md#artifacts-configuration).
121+
122+
#### Log plugin
123+
124+
To be done. See meanwhile the example in [APIRef.Configuration.md#artifacts-configuration](APIRef.Configuration.md#artifacts-configuration).
125+
126+
#### Instruments plugin
127+
128+
To be done. See meanwhile the example in [APIRef.Configuration.md#artifacts-configuration](APIRef.Configuration.md#artifacts-configuration).
129+
28130
## Artifacts structure
29131

30132
1. **Artifacts root folder** is created per detox test run. If, for instance,`--artifacts-location /tmp` is used with `--configuration ios.sim.release` configuration on 14th June 2018 at 11:02:11 GMT+02, then the folder `/tmp/ios.sim.release.2018-06-14 09:02:11Z` is created.

0 commit comments

Comments
 (0)