testronaut 1.2.1 β 1.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -109
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
# π§βπ Testronaut
|
|
2
2
|
|
|
3
|
-
**Testronaut** is an autonomous testing framework powered by
|
|
3
|
+
**Testronaut** is an autonomous testing framework powered by **LLMs and Playwright**.
|
|
4
|
+
It lets you define *mission-based tests* in plain English, then runs them through a real browser to validate UI workflows β all while generating human-readable reports.
|
|
4
5
|
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
## π Join the Mission Control Community
|
|
8
9
|
|
|
9
|
-
Got questions, ideas, or
|
|
10
|
-
Join
|
|
10
|
+
Got questions, ideas, or missions to share?
|
|
11
|
+
Join the Discord to connect with other Testronauts, get support, and help shape the frameworkβs future.
|
|
11
12
|
|
|
12
13
|
[](https://discord.gg/pBfdef92ba)
|
|
13
14
|
|
|
@@ -15,46 +16,52 @@ Join our Discord to connect with other Testronauts, get support, and help shape
|
|
|
15
16
|
|
|
16
17
|
## π Features
|
|
17
18
|
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
19
|
+
- Write tests in plain English β no brittle selectors
|
|
20
|
+
- Runs real browser sessions via **Playwright**
|
|
21
|
+
- Works with **multiple LLM providers** (OpenAI, Google Gemini, and more coming)
|
|
22
|
+
- Modular tool and DOM-reasoning system
|
|
23
|
+
- Dynamic rate-limit and token-tracking logic
|
|
24
|
+
- Generates JSON + HTML reports automatically
|
|
24
25
|
|
|
25
26
|
---
|
|
26
27
|
|
|
27
28
|
## π Documentation
|
|
28
29
|
|
|
29
30
|
Looking for deeper guides, API references, and examples?
|
|
30
|
-
|
|
31
|
+
Check the official docs:
|
|
31
32
|
|
|
32
33
|
[](https://docs.testronaut.app)
|
|
33
34
|
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
- Writing advanced missions
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
35
|
+
Includes:
|
|
36
|
+
- Quickstart and setup
|
|
37
|
+
- Writing advanced missions
|
|
38
|
+
- Configuring providers and models
|
|
39
|
+
- CLI options
|
|
40
|
+
- Mission Control integration
|
|
41
|
+
- Troubleshooting and FAQs
|
|
40
42
|
|
|
41
43
|
---
|
|
42
44
|
|
|
43
45
|
## π¦ Installation
|
|
44
46
|
|
|
45
|
-
```
|
|
47
|
+
```bash
|
|
46
48
|
npm install -g testronaut
|
|
47
49
|
```
|
|
48
|
-
|
|
49
|
-
|
|
50
|
+
|
|
51
|
+
Then initialize your project:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
50
54
|
npx testronaut --init
|
|
51
55
|
```
|
|
52
|
-
|
|
53
|
-
|
|
56
|
+
|
|
57
|
+
Run the sample mission:
|
|
58
|
+
```bash
|
|
54
59
|
npx testronaut welcome.mission.js
|
|
55
60
|
```
|
|
56
|
-
|
|
57
|
-
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## π Project Structure
|
|
58
65
|
|
|
59
66
|
```
|
|
60
67
|
missions/
|
|
@@ -62,142 +69,137 @@ missions/
|
|
|
62
69
|
βββ logout.mission.js
|
|
63
70
|
βββ dashboard.mission.js
|
|
64
71
|
```
|
|
65
|
-
Each file exports a mission string or function and invokes runMissions.
|
|
66
72
|
|
|
67
|
-
|
|
68
|
-
Create a file in your missions/ directory, e.g. missions/login.mission.js:
|
|
73
|
+
Each mission exports a string or function and calls `runMissions`.
|
|
69
74
|
|
|
70
|
-
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## βοΈ Example Mission
|
|
78
|
+
|
|
79
|
+
```js
|
|
71
80
|
import { runMissions } from 'testronaut';
|
|
72
81
|
|
|
73
82
|
export const loginMission = `
|
|
74
83
|
Visit ${process.env.URL}.
|
|
75
|
-
Fill the username field with ${process.env.USERNAME}.
|
|
84
|
+
Fill the username field with ${process.env.USERNAME}.
|
|
76
85
|
Fill the password field with ${process.env.PASSWORD}.
|
|
77
|
-
|
|
78
|
-
Submit the form.
|
|
86
|
+
Click the Login button.
|
|
79
87
|
Wait for the dashboard to appear.
|
|
80
|
-
Take
|
|
81
|
-
Report SUCCESS if the dashboard is loaded, otherwise
|
|
88
|
+
Take a screenshot.
|
|
89
|
+
Report SUCCESS if the dashboard is loaded, otherwise FAILURE.
|
|
82
90
|
`;
|
|
83
91
|
|
|
84
92
|
export async function executeMission() {
|
|
85
|
-
await runMissions({
|
|
86
|
-
mission: loginMission
|
|
87
|
-
}, "Login Mission");
|
|
93
|
+
await runMissions({ mission: loginMission }, "Login Mission");
|
|
88
94
|
}
|
|
89
95
|
```
|
|
90
96
|
|
|
91
|
-
|
|
97
|
+
Create a `.env` file with your credentials **and LLM API key** (depending on your chosen provider):
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# For OpenAI
|
|
101
|
+
OPENAI_API_KEY=sk-...
|
|
102
|
+
|
|
103
|
+
# Or for Gemini
|
|
104
|
+
GEMINI_API_KEY=AIza...
|
|
92
105
|
|
|
93
|
-
```
|
|
94
|
-
OPENAI_API_KEY=sk-proj-############
|
|
95
106
|
URL=https://example.com/login
|
|
96
107
|
USERNAME=example@example.com
|
|
97
108
|
PASSWORD=********
|
|
98
109
|
```
|
|
99
110
|
|
|
100
|
-
|
|
111
|
+
---
|
|
101
112
|
|
|
102
|
-
|
|
103
|
-
import { runMissions } from 'testronaut';
|
|
104
|
-
import { loginMission } from './login.mission.js';
|
|
105
|
-
import { logoutMission } from './logout.mission.js';
|
|
106
|
-
import { navigateToContactFormMission } from './navigateToContactForm.mission.js';
|
|
107
|
-
|
|
108
|
-
export const fillContactFormMission =
|
|
109
|
-
`Input the text "example@example.com" in the email field.
|
|
110
|
-
Input the phone number (555)555-5555 into the phone number field.
|
|
111
|
-
Click the submit button.
|
|
112
|
-
Upon submission success there should be a toast notification indicating the form information was saved successfully.
|
|
113
|
-
Take a screenshot.
|
|
114
|
-
If found, report SUCCESS. Otherwise, report FAILURE.`
|
|
113
|
+
## π§ LLM Provider Support
|
|
115
114
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
preMission: [loginMission, navigateToContactFormMission],
|
|
119
|
-
mission: fillContactFormMission,
|
|
120
|
-
postMission: logoutMission,
|
|
121
|
-
}, "Fill Contact Form Mission");
|
|
122
|
-
}
|
|
123
|
-
```
|
|
115
|
+
Testronaut is provider-agnostic.
|
|
116
|
+
Choose your preferred LLM at init or via environment variables.
|
|
124
117
|
|
|
125
|
-
|
|
126
|
-
|
|
118
|
+
```bash
|
|
119
|
+
# During init
|
|
120
|
+
npx testronaut --init
|
|
127
121
|
|
|
122
|
+
# Or override anytime
|
|
123
|
+
TESTRONAUT_PROVIDER=gemini TESTRONAUT_MODEL=gemini-2.5-pro npx testronaut
|
|
128
124
|
```
|
|
125
|
+
|
|
126
|
+
Current supported providers:
|
|
127
|
+
|
|
128
|
+
| Provider | Example Models |
|
|
129
|
+
|-----------|----------------|
|
|
130
|
+
| **OpenAI** | gpt-4o, gpt-4.1, o3, gpt-5, etc. |
|
|
131
|
+
| **Google Gemini** | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-8b |
|
|
132
|
+
|
|
133
|
+
More providers coming soon (Anthropic, Mistral, etc.).
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## π Running Missions
|
|
138
|
+
|
|
139
|
+
Run all missions:
|
|
140
|
+
```bash
|
|
129
141
|
npx testronaut
|
|
130
142
|
```
|
|
131
|
-
Run a specific file:
|
|
132
143
|
|
|
133
|
-
|
|
144
|
+
Run a specific mission:
|
|
145
|
+
```bash
|
|
134
146
|
npx testronaut login.mission.js
|
|
135
147
|
```
|
|
136
148
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
149
|
+
Chain missions together:
|
|
150
|
+
```js
|
|
151
|
+
await runMissions({
|
|
152
|
+
preMission: [loginMission],
|
|
153
|
+
mission: fillContactFormMission,
|
|
154
|
+
postMission: logoutMission,
|
|
155
|
+
}, "Contact Form Flow");
|
|
141
156
|
```
|
|
142
|
-
|
|
157
|
+
---
|
|
143
158
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
β Optional suite syntax
|
|
159
|
+
## π Reports
|
|
160
|
+
|
|
161
|
+
Testronaut generates both JSON and HTML reports automatically under:
|
|
148
162
|
|
|
149
163
|
```
|
|
150
|
-
|
|
164
|
+
missions/mission_reports/
|
|
151
165
|
```
|
|
152
|
-
β Executes all registered test objectives
|
|
153
|
-
|
|
154
|
-
### π Reports
|
|
155
|
-
HTML and JSON reports automatically created in the ```missions/mission_reports/``` directory for each testronaut run
|
|
156
166
|
|
|
157
|
-
|
|
158
|
-
|
|
167
|
+
Each includes:
|
|
168
|
+
- Steps executed
|
|
169
|
+
- Token usage
|
|
170
|
+
- Screenshots
|
|
171
|
+
- Pass/Fail summaries
|
|
159
172
|
|
|
160
|
-
|
|
173
|
+
---
|
|
161
174
|
|
|
162
|
-
|
|
175
|
+
## π§ͺ Under the Hood
|
|
163
176
|
|
|
164
|
-
|
|
165
|
-
|
|
177
|
+
- **Playwright** for browser automation
|
|
178
|
+
- **LLMs** for reasoning, DOM parsing, and tool use
|
|
179
|
+
- **Token throttling** + adaptive cooldowns
|
|
180
|
+
- **Extensible architecture** for custom tools and workflows
|
|
166
181
|
|
|
167
|
-
|
|
168
|
-
npm install
|
|
169
|
-
npm link
|
|
170
|
-
```
|
|
171
|
-
Now you can use testronaut in any local project.
|
|
182
|
+
---
|
|
172
183
|
|
|
173
|
-
|
|
174
|
-
MIT
|
|
184
|
+
## π§ Mission Control
|
|
175
185
|
|
|
176
|
-
|
|
186
|
+
[Mission Control](https://mission.testronaut.app) lets you:
|
|
187
|
+
- View all reports in one dashboard
|
|
188
|
+
- Track mission history and success rates
|
|
189
|
+
- Compare results across environments
|
|
190
|
+
- Access screenshots and step details anytime
|
|
177
191
|
|
|
178
|
-
|
|
179
|
-
Want to see your test results evolve, spot trends, and keep all your reports in one place?
|
|
180
|
-
Sign up for **Mission Control** β your personal dashboard for Testronaut.
|
|
192
|
+
---
|
|
181
193
|
|
|
182
|
-
|
|
183
|
-
- π Track your mission reports historically
|
|
184
|
-
- π Drill into past runs with full step-by-step details
|
|
185
|
-
- π οΈ Compare results between different builds or environments
|
|
186
|
-
- βοΈ Access reports from anywhere, without digging through local files
|
|
194
|
+
## π License
|
|
187
195
|
|
|
188
|
-
|
|
189
|
-
1. [](https://mission.testronaut.app)
|
|
190
|
-
2. Link your account to Testronaut CLI
|
|
191
|
-
3. Watch your mission history grow!
|
|
196
|
+
MIT
|
|
192
197
|
|
|
193
198
|
---
|
|
194
199
|
|
|
195
200
|
## β Support the Mission
|
|
196
|
-
π€ Built with β€οΈ by [Shane Fast](https://github.com/scfast)
|
|
197
201
|
|
|
198
|
-
|
|
199
|
-
Your support helps cover hosting, development time, and the occasional coffee needed to debug at 2am.
|
|
202
|
+
π€ Built with β€οΈ by [Shane Fast](https://github.com/scfast)
|
|
200
203
|
|
|
204
|
+
If Testronaut saves you time, consider fueling the mission:
|
|
201
205
|
[](https://buymeacoffee.com/testronaut)
|
|
202
|
-
|
|
203
|
-
---
|