Skip to content

Commit 3577f4f

Browse files
promptless[bot]hawkeyexl
promptless[bot]
and
hawkeyexl
authored
docs: Add documentation for saveCookie and loadCookie actions (#83)
* Documentation updates from Promptless * Updated dependencies * Updated content * Fixed typos --------- Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com> Co-authored-by: hawkeyexl <[email protected]>
1 parent bf228b5 commit 3577f4f

File tree

14 files changed

+619
-76
lines changed

14 files changed

+619
-76
lines changed

‎docs/get-started/actions/loadCookie.mdx‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
title: loadCookie
3+
layout: default
4+
nav_order: 1
5+
parent: Actions
6+
grand_parent: Tests
7+
description: Load a cookie from a file or environment variable into the browser.
8+
---
9+
10+
# loadCookie
11+
12+
The `loadCookie` action loads a cookie from a file or environment variable into the browser. This action is useful for restoring authentication sessions, user preferences, or other stateful information that was previously saved using the [`saveCookie`](/docs/get-started/actions/saveCookie) action.
13+
14+
> For comprehensive options, see the [`loadCookie`](/docs/references/schemas/loadcookie) reference.
15+
16+
## Use cases
17+
18+
- **Session restoration**: Load previously saved authentication cookies to skip login steps
19+
- **Test setup optimization**: Reduce test execution time by reusing authentication state
20+
- **Cross-test data sharing**: Share cookies between different test specifications
21+
- **CI/CD integration**: Load authentication state from environment variables in automated pipelines
22+
- **Test isolation**: Ensure consistent starting state by loading known cookie values
23+
- **Multi-user testing**: Load different user sessions for testing various user roles
24+
25+
## Formats
26+
27+
The `loadCookie` action supports multiple formats:
28+
29+
### String format
30+
31+
Load a cookie by name from default location or by file path:
32+
33+
```json title="Load from environment variable"
34+
{
35+
"loadCookie": "session_token"
36+
}
37+
```
38+
39+
```json title="Load from file"
40+
{
41+
"loadCookie": "session_token.txt"
42+
}
43+
```
44+
45+
### Object format
46+
47+
Load a cookie with detailed configuration:
48+
49+
```json
50+
{
51+
"loadCookie": {
52+
"name": "auth_cookie",
53+
"path": "auth-session.txt",
54+
"directory": "./test-data"
55+
}
56+
}
57+
```
58+
59+
## Configuration options
60+
61+
| Field | Type | Description | Default |
62+
|-------|------|-------------|---------|
63+
| `name` | string | **Required.** Name of the specific cookie to load. | |
64+
| `variable` | string | Environment variable name containing the cookie as JSON string. Can't be used with `path`. | |
65+
| `path` | string | File path to cookie file, relative to directory. Supports Netscape cookie format. Can't be used with `variable`. | |
66+
| `directory` | string | Directory containing the cookie file. | |
67+
| `domain` | string | Specific domain to filter the cookie by when loading from multi-cookie file (optional). | |
68+
69+
## Examples
70+
71+
### Load from default location
72+
73+
```json
74+
{
75+
"steps": [
76+
{
77+
"description": "Load saved session cookie",
78+
"loadCookie": "session_token"
79+
},
80+
{
81+
"description": "Navigate to protected page",
82+
"goTo": "https://example.com/dashboard"
83+
}
84+
]
85+
}
86+
```
87+
88+
### Load from specific file
89+
90+
```json
91+
{
92+
"steps": [
93+
{
94+
"description": "Load authentication cookie from file",
95+
"loadCookie": {
96+
"name": "auth_cookie",
97+
"path": "auth-session.txt",
98+
"directory": "./test-data"
99+
}
100+
}
101+
]
102+
}
103+
```
104+
105+
### Load from environment variable
106+
107+
```json
108+
{
109+
"steps": [
110+
{
111+
"description": "Load session cookie from environment variable",
112+
"loadCookie": {
113+
"name": "session_token",
114+
"variable": "SESSION_TOKEN"
115+
}
116+
}
117+
]
118+
}
119+
```
120+
121+
### Load with domain filtering
122+
123+
```json
124+
{
125+
"steps": [
126+
{
127+
"description": "Load cookie for specific domain from multi-cookie file",
128+
"loadCookie": {
129+
"name": "user_session",
130+
"path": "saved-cookies.txt",
131+
"domain": "app.example.com"
132+
}
133+
}
134+
]
135+
}
136+
```
137+
138+
### Complete workflow example
139+
140+
```json
141+
{
142+
"tests": [
143+
{
144+
"description": "Setup test - authenticate and save session",
145+
"steps": [
146+
{
147+
"description": "Navigate to login page",
148+
"goTo": "https://example.com/login"
149+
},
150+
{
151+
"description": "Enter credentials and login",
152+
"find": {
153+
"elementText": "Username",
154+
"type": "testuser"
155+
}
156+
},
157+
{
158+
"description": "Save authentication cookie",
159+
"saveCookie": {
160+
"name": "session_token",
161+
"path": "session.txt"
162+
}
163+
}
164+
]
165+
},
166+
{
167+
"description": "Main test - use saved session",
168+
"steps": [
169+
{
170+
"description": "Load saved authentication cookie",
171+
"loadCookie": {
172+
"name": "session_token",
173+
"path": "session.txt"
174+
}
175+
},
176+
{
177+
"description": "Navigate directly to protected page",
178+
"goTo": "https://example.com/dashboard"
179+
},
180+
{
181+
"description": "Verify authenticated access",
182+
"find": {
183+
"elementText": "Welcome back"
184+
}
185+
}
186+
]
187+
}
188+
]
189+
}
190+
```
191+
192+
## Related actions
193+
194+
- [`saveCookie`](/docs/get-started/actions/saveCookie): Save a browser cookie to a file or environment variable
195+
- [`loadVariables`](/docs/get-started/actions/loadVariables): Load environment variables from .env files

‎docs/get-started/actions/saveCookie.mdx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: saveCookie
3+
layout: default
4+
nav_order: 1
5+
parent: Actions
6+
grand_parent: Tests
7+
description: Save a browser cookie to a file or environment variable for later reuse.
8+
---
9+
10+
# saveCookie
11+
12+
The `saveCookie` action saves a browser cookie to a file or environment variable for later reuse. This action is useful for preserving authentication sessions, user preferences, or other stateful information between test runs or across different tests.
13+
14+
Reload saved cookies with the [`loadCookie`](/docs/get-started/actions/loadCookie) action.
15+
16+
> For comprehensive options, see the [`saveCookie`](/docs/references/schemas/savecookie) reference.
17+
18+
## Use cases
19+
20+
- **Session persistence**: Save authentication cookies to maintain login state across test runs
21+
- **Multi-step workflows**: Preserve cookies between different test specifications
22+
- **Cross-browser testing**: Transfer cookies between different browser contexts
23+
- **CI/CD integration**: Store authentication state as environment variables for automated testing
24+
- **Test data management**: Save cookies to files for debugging and test data inspection
25+
26+
## Formats
27+
28+
The `saveCookie` action supports multiple formats:
29+
30+
### String format
31+
32+
Save a cookie by name to a default location:
33+
34+
```json title="Save to environment variable"
35+
{
36+
"saveCookie": "session_token"
37+
}
38+
```
39+
40+
```json title="Save to file"
41+
{
42+
"saveCookie": "session_token.txt"
43+
}
44+
```
45+
46+
### Object format
47+
48+
Save a cookie with detailed configuration:
49+
50+
```json
51+
{
52+
"saveCookie": {
53+
"name": "auth_cookie",
54+
"path": "auth-session.txt",
55+
"directory": "./test-data",
56+
"overwrite": "true"
57+
}
58+
}
59+
```
60+
61+
## Configuration options
62+
63+
| Field | Type | Description | Default |
64+
|-------|------|-------------|---------|
65+
| `name` | string | **Required.** Name of the specific cookie to save. | |
66+
| `variable` | string | Environment variable name to store the cookie as JSON string. Can't be used with `path`. | |
67+
| `path` | string | File path to save the cookie, relative to directory. Uses Netscape cookie format. Can't be used with `variable`. | |
68+
| `directory` | string | Directory to save the cookie file. If not specified, uses output directory. | |
69+
| `overwrite` | string | Whether to overwrite existing cookie file. Options: `"true"`, `"false"`. | `"false"` |
70+
| `domain` | string | Specific domain to filter the cookie by (optional). | |
71+
72+
## Examples
73+
74+
### Save to default location
75+
76+
```json
77+
{
78+
"steps": [
79+
{
80+
"description": "Navigate to login page and authenticate",
81+
"goTo": "https://example.com/login"
82+
},
83+
{
84+
"description": "Fill in login credentials",
85+
"find": {
86+
"elementText": "Username",
87+
"type": "testuser"
88+
}
89+
},
90+
{
91+
"description": "Save the session cookie after login",
92+
"saveCookie": "session_token"
93+
}
94+
]
95+
}
96+
```
97+
98+
### Save to specific file
99+
100+
```json
101+
{
102+
"steps": [
103+
{
104+
"description": "Save authentication cookie to specific file",
105+
"saveCookie": {
106+
"name": "auth_cookie",
107+
"path": "auth-session.txt",
108+
"directory": "./test-data",
109+
"overwrite": "true"
110+
}
111+
}
112+
]
113+
}
114+
```
115+
116+
### Save to environment variable
117+
118+
```json
119+
{
120+
"steps": [
121+
{
122+
"description": "Save session cookie to environment variable",
123+
"saveCookie": {
124+
"name": "session_token",
125+
"variable": "SESSION_TOKEN"
126+
}
127+
}
128+
]
129+
}
130+
```
131+
132+
### Save with domain filtering
133+
134+
```json
135+
{
136+
"steps": [
137+
{
138+
"description": "Save cookie for specific domain",
139+
"saveCookie": {
140+
"name": "login_token",
141+
"path": "login-token.txt",
142+
"domain": "app.example.com"
143+
}
144+
}
145+
]
146+
}
147+
```
148+
149+
## Related actions
150+
151+
- [`loadCookie`](/docs/get-started/actions/loadCookie): Load a saved cookie back into the browser
152+
- [`loadVariables`](/docs/get-started/actions/loadVariables): Load environment variables from .env files

‎docs/get-started/concepts.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ An action is the task performed in a step. Doc Detective supports a variety of a
3232
| [runShell](/docs/get-started/actions/runShell) | Perform a native shell command. |
3333
| [screenshot](/docs/get-started/actions/screenshot) | Take a screenshot in PNG format. |
3434
| [loadVariables](/docs/get-started/actions/loadVariables) | Load environment variables from a `.env` file. |
35+
| [saveCookie](/docs/get-started/actions/saveCookie) | Save a specific browser cookie to a file or environment variable for later reuse. |
36+
| [loadCookie](/docs/get-started/actions/loadCookie) | Load a specific cookie from a file or environment variable into the browser. |
3537
| [record](/docs/get-started/actions/record) | Capture a video of test run. |
3638
| [stopRecord](/docs/get-started/actions/stopRecord) | Stop capturing a video of test run. |
3739
| [type](/docs/get-started/actions/type) | Type keys. To type special keys, begin and end the string with `$` and use the special key’s enum. For example, to type the Escape key, enter `$ESCAPE$`. |

‎docs/get-started/tests/index.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ Tests tell Doc Detective what actions to perform, how, and where. Tests are made
2323
- [**goTo**](/docs/get-started/actions/goTo): Navigate to a specified URL.
2424
- [**httpRequest**](/docs/get-started/actions/httpRequest): Perform a generic HTTP request, for example to an API.
2525
- [**loadVariables**](/docs/get-started/actions/loadVariables): Load environment variables from a `.env` file.
26+
- [**saveCookie**](/docs/get-started/actions/saveCookie): Save a specific browser cookie to a file or environment variable for later reuse.
27+
- [**loadCookie**](/docs/get-started/actions/loadCookie): Load a specific cookie from a file or environment variable into the browser.
2628
- [**record**](/docs/get-started/actions/record) and [**stopRecord**](/docs/get-started/actions/stopRecord): Capture a video of test execution.
2729
- [**runCode**](/docs/get-started/actions/runCode): Assemble and run code.
2830
- [**runShell**](/docs/get-started/actions/runShell): Perform a native shell command.
@@ -537,6 +539,22 @@ Load environment variables from an `.env` file, where the path is the match.
537539
{ "loadVariables": "$1" }
538540
```
539541

542+
#### `saveCookie`
543+
544+
Save a browser cookie by name to a default location.
545+
546+
```json
547+
{ "saveCookie": "$1" }
548+
```
549+
550+
#### `loadCookie`
551+
552+
Load a browser cookie by name from a default location.
553+
554+
```json
555+
{ "loadCookie": "$1" }
556+
```
557+
540558
## Run tests
541559

542560
Doc Detective's `doc-detective` command runs your tests. Input files are read from your config's `input` property, but you can also specify input files directly in the command with the `--input` flag.

0 commit comments

Comments
 (0)