Skip to content

Commit e50f393

Browse files
sonic16xsonic16x
authored
feat(testplane): docs for saveState and restoreState
1 parent 164c0a1 commit e50f393

File tree

10 files changed

+674
-0
lines changed

10 files changed

+674
-0
lines changed

‎docs/_partials/specs/version-en.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_Available from testplane v{props.version}_

‎docs/_partials/specs/version-ru.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_Доступно начиная с testplane v{props.version}_

‎docs/commands/browser/restoreState.mdx‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
import Admonition from "@theme/Admonition";
2+
import Version from "../../_partials/specs/version-en.mdx";
3+
4+
# restoreState
5+
6+
<Version version="8.33.0" />
7+
8+
## Overview {#overview}
9+
10+
Browser command that restores session state (cookies, local and session storages) from a file or variable.
11+
12+
## Usage {#usage}
13+
14+
You can restore the browser state from either a file (using the `path` parameter) or directly from an object (using the `data` parameter).
15+
16+
**Important:** If you provide both `path` and `data` parameters, the file specified in `path` will take priority.
17+
18+
You can optionally specify which storage types to restore using the `cookies`, `localStorage`, and `sessionStorage` parameters. This allows you to restore only the specific data you need.
19+
20+
The state data for restoration can be obtained from the [saveState](../saveState) command.
21+
22+
<Admonition type="warning">
23+
You must be on the exact same page from which the cookies were originally saved. You need to
24+
navigate to the page first, use the [url](../url) command before restoring state.
25+
</Admonition>
26+
27+
```typescript
28+
await browser.restoreState({
29+
path: "./stateDump.json",
30+
data: stateDump,
31+
cookies: true,
32+
localStorage: true,
33+
sessionStorage: true,
34+
});
35+
```
36+
37+
## Command Parameters {#parameters}
38+
39+
<table>
40+
<thead>
41+
<tr>
42+
<td>**Name**</td>
43+
<td>**Type**</td>
44+
<td>**Default**</td>
45+
<td>**Description**</td>
46+
</tr>
47+
</thead>
48+
<tbody>
49+
<tr>
50+
<td>path</td>
51+
<td>`string`</td>
52+
<td>`-`</td>
53+
<td>Path to file with state.</td>
54+
</tr>
55+
<tr>
56+
<td>data</td>
57+
<td>`SaveStateData`</td>
58+
<td>`-`</td>
59+
<td>Object with state.</td>
60+
</tr>
61+
<tr>
62+
<td>cookies</td>
63+
<td>`boolean`</td>
64+
<td>`true`</td>
65+
<td>Enable restore cookies.</td>
66+
</tr>
67+
<tr>
68+
<td>localStorage</td>
69+
<td>`boolean`</td>
70+
<td>`true`</td>
71+
<td>Enable restore localStorage.</td>
72+
</tr>
73+
<tr>
74+
<td>sessionStorage</td>
75+
<td>`boolean`</td>
76+
<td>`true`</td>
77+
<td>Enable restore sessionStorage.</td>
78+
</tr>
79+
<tr>
80+
<td>cookieFilter</td>
81+
<td>`(cookie: Cookie) => boolean`</td>
82+
<td>`-`</td>
83+
<td>
84+
Function for filtering cookies, receiving cookie objects, and returning boolean.
85+
</td>
86+
</tr>
87+
</tbody>
88+
</table>
89+
90+
## Usage Examples {#examples}
91+
92+
Restore state from file.
93+
94+
```typescript
95+
it("test", async ({ browser }) => {
96+
await browser.url("https://github.com/gemini-testing/testplane");
97+
98+
await browser.restoreState({
99+
path: "./stateDump.json",
100+
cookieFilter: ({ domain }) => domain === ".example.com",
101+
});
102+
103+
// Reload page for see auth result.
104+
await browser.refresh();
105+
});
106+
```
107+
108+
Example of implementing authentication in tests with saveState/restoreState and beforeAll hook.
109+
110+
```typescript
111+
import { ConfigInput, WdioBrowser } from "testplane";
112+
import { launchBrowser } from "testplane/unstable";
113+
114+
export default {
115+
gridUrl: "local",
116+
beforeAll: async ({ config }) => {
117+
const b = await launchBrowser(config.browsers["chrome"]!);
118+
119+
await b.url("https://our-site.com");
120+
await b.$("input.login").setValue("[email protected]");
121+
await b.$("input.password").setValue("password123");
122+
123+
await b.saveState({ path: "./.testplane/state.json" });
124+
await b.deleteSession();
125+
},
126+
sets: {
127+
/* ... */
128+
},
129+
browsers: {
130+
chrome: {
131+
headless: false,
132+
desiredCapabilities: {
133+
browserName: "chrome",
134+
},
135+
},
136+
},
137+
plugins: {
138+
/* ... */
139+
"@testplane/global-hook": {
140+
enabled: true,
141+
beforeEach: async ({ browser }: { browser: WdioBrowser }) => {
142+
await browser.url("https://our-site.com");
143+
await browser.restoreState({ path: "./.testplane/state.json" });
144+
},
145+
},
146+
},
147+
} satisfies ConfigInput;
148+
```
149+
150+
## Related Commands {#related}
151+
152+
- [saveState](../saveState)
153+
- [afterAll](../../../config/after-all)
154+
- [beforeAll](../../../config/before-all)

‎docs/commands/browser/saveState.mdx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
import Version from "../../_partials/specs/version-en.mdx";
2+
3+
# saveState
4+
5+
<Version version="8.33.0" />
6+
7+
## Overview {#overview}
8+
9+
Browser command that saves session state (cookies, local and session storages).
10+
11+
## Usage {#usage}
12+
13+
This command returns a state of the page state, including cookies, localStorage, and sessionStorage.
14+
You can use parameters to exclude specific types of data if needed.
15+
16+
If you provide the `path` parameter, the state dump will be saved to a file.
17+
The saved state can later be restored using the [restoreState](../restoreState) command.
18+
19+
```typescript
20+
import type { SaveStateData } from "testplane";
21+
22+
const stateDump: SaveStateData = await browser.saveState({
23+
path: "./stateDump.json",
24+
cookies: true,
25+
localStorage: true,
26+
sessionStorage: true,
27+
});
28+
```
29+
30+
## Command Parameters {#parameters}
31+
32+
<table>
33+
<thead>
34+
<tr>
35+
<td>**Name**</td>
36+
<td>**Type**</td>
37+
<td>**Default**</td>
38+
<td>**Description**</td>
39+
</tr>
40+
</thead>
41+
<tbody>
42+
<tr>
43+
<td>path</td>
44+
<td>`string`</td>
45+
<td>`-`</td>
46+
<td>Path to file where state will be saved.</td>
47+
</tr>
48+
<tr>
49+
<td>cookies</td>
50+
<td>`boolean`</td>
51+
<td>`true`</td>
52+
<td>Enable save cookies.</td>
53+
</tr>
54+
<tr>
55+
<td>localStorage</td>
56+
<td>`boolean`</td>
57+
<td>`true`</td>
58+
<td>Enable save localStorage.</td>
59+
</tr>
60+
<tr>
61+
<td>sessionStorage</td>
62+
<td>`boolean`</td>
63+
<td>`true`</td>
64+
<td>Enable save sessionStorage.</td>
65+
</tr>
66+
<tr>
67+
<td>cookieFilter</td>
68+
<td>`(cookie: Cookie) => boolean`</td>
69+
<td>`-`</td>
70+
<td>
71+
Function for filtering cookies, receiving cookie objects, and returning boolean.
72+
</td>
73+
</tr>
74+
</tbody>
75+
</table>
76+
77+
## Usage Examples {#examples}
78+
79+
Save state in file.
80+
81+
```typescript
82+
it("test", async ({ browser }) => {
83+
await browser.url("https://github.com/gemini-testing/testplane");
84+
85+
await browser.saveState({
86+
path: "./stateDump.json",
87+
cookieFilter: ({ domain }) => domain === ".example.com",
88+
});
89+
});
90+
```
91+
92+
## Related Commands {#related}
93+
94+
- [restoreState](../restoreState)
95+
- [afterAll](../../../config/after-all)
96+
- [beforeAll](../../../config/before-all)

‎docs/config/after-all.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import Version from "../_partials/specs/version-en.mdx";
2+
3+
# afterAll
4+
5+
<Version version="8.33.0" />
6+
7+
## Overview {#overview}
8+
9+
This parameter is a hook. The function specified for this parameter will be automatically called after tests are completed.
10+
11+
The context of the function is the Testplane config. Function receives config in arguments.
12+
13+
## Usage Example {#example}
14+
15+
Here is an example of using this hook to remove a file with a page state.
16+
17+
```typescript title="testplane.config.ts"
18+
import * as fs from "fs";
19+
20+
export default {
21+
// ...
22+
afterAll: async () => {
23+
await fs.unlink("./dump.json");
24+
},
25+
};
26+
```
27+
28+
## Related {#related}
29+
30+
- [beforeAll](../before-all)

‎docs/config/before-all.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
import Version from "../_partials/specs/version-en.mdx";
2+
3+
# beforeAll
4+
5+
<Version version="8.33.0" />
6+
7+
## Overview {#overview}
8+
9+
This parameter is a hook. The function specified for this parameter will be automatically called before tests running.
10+
11+
The context of the function is the Testplane config. Also function receives config in arguments.
12+
13+
## Usage Example {#example}
14+
15+
Here is an example of using this hook for logging in and getting session data for use in tests.
16+
17+
```typescript title="testplane.config.ts"
18+
import { launchBrowser } from "testplane/unstable";
19+
20+
export default {
21+
// ...
22+
browsers: {
23+
chrome: {
24+
headless: true,
25+
desiredCapabilities: {
26+
webSocketUrl: true,
27+
browserName: "chrome",
28+
},
29+
},
30+
firefox: {
31+
headless: true,
32+
desiredCapabilities: {
33+
webSocketUrl: true,
34+
browserName: "firefox",
35+
},
36+
},
37+
},
38+
beforeAll: async () => {
39+
// launch a new browser with existing config
40+
const browser = await launchBrowser(this.config.browsers.chrome);
41+
42+
await browser.url("https://example.com");
43+
44+
// do login things, type username/password etc.
45+
46+
// save dump with state (cookies, localStorage) for using in tests
47+
await browser.saveState({
48+
path: "./dump.json",
49+
});
50+
51+
await browser.deleteSession();
52+
},
53+
};
54+
```
55+
56+
## Related {#related}
57+
58+
- [afterAll](../after-all)

0 commit comments

Comments
 (0)