Skip to content

Commit db437f5

Browse files
jennifer-shehanejennifer-shehane
committed
docs: begin writing cy.prompt docs
1 parent a9f2740 commit db437f5

File tree

4 files changed

+364
-0
lines changed

4 files changed

+364
-0
lines changed

‎docs/api/commands/prompt.mdx‎

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
---
2+
title: 'cy.prompt() | Cypress Documentation'
3+
description: Use natural language to generate Cypress tests with AI. Write steps in plain English and let Cypress do the rest.
4+
sidebar_label: prompt
5+
slug: /api/commands/prompt
6+
e2eSpecific: true
7+
sidebar_custom_props: { 'new_label': true }
8+
---
9+
10+
<ProductHeading product="cloud" />
11+
12+
# prompt
13+
14+
`cy.prompt` is an AI-powered Cypress command that turns plain English test steps into executable Cypress code. It offers a fast way to explore new test flows, bootstrap end-to-end coverage, and prototype without writing selectors or commands by hand. It is available on all Cypress Cloud plan types.
15+
16+
:::note
17+
18+
<strong>Before you start coding with `cy.prompt`</strong>
19+
20+
21+
- [How it works](#how-it-works) — code generation, caching, and self-healing
22+
- [Writing effective prompts](#writing-effective-prompts) — patterns that work best
23+
- [Selectors](#how-selectors-are-chosen) — how Cypress selects elements automatically
24+
- [Debugging & transparency](#debugging--transparency) — inspect generated code and save it for version control
25+
- [Setup](#setup) — setup and prerequisites
26+
- [Limitations](#limitations) — what is and is not supported today
27+
- [Pricing, limits, and security](#pricing--availability)
28+
29+
:::
30+
31+
<DocsVideo
32+
src="/img/api/prompt/cy-prompt-demo.mp4"
33+
autoPlay={true}
34+
title="cy.prompt written for login screen using Cypress Studio"
35+
/>
36+
37+
*The demo above shows `cy.prompt` in action with [Cypress Studio](/app/guides/cypress-studio).*
38+
39+
## Syntax
40+
41+
42+
```typescript
43+
interface PromptCommand {
44+
(
45+
steps: string[], // array of steps to execute
46+
options?: {
47+
excludeFromAI?: string[] // keys to exclude from AI (e.g. sensitive vars)
48+
}
49+
): void
50+
}
51+
```
52+
53+
**Example**
54+
55+
```typescript
56+
cy.prompt([
57+
'visit https://cloud.cypress.io/login',
58+
'type "[email protected]" in the email field',
59+
'type ${password} in the password field',
60+
'click the login button'
61+
], {
62+
excludeFromAI: ['password']
63+
})
64+
```
65+
66+
<HeaderYields />
67+
68+
- `cy.prompt()` yields `null`.
69+
70+
71+
## How it works
72+
73+
When you call `cy.prompt`, Cypress performs a multi-step process:
74+
75+
1. **Interpret prompt:** Each string in your `steps[]` array is parsed using an AI model. Cypress maps the intent (e.g. 'click the login button') to Cypress commands (`cy.get(...).click()`) and target elements.
76+
77+
2. **Generate selectors:** Cypress evaluates your app's DOM and picks a selector based on priority rules (unique identifiers that are likely to be stable).
78+
79+
3. **Generate Cypress code:** Commands are generated and executed in sequence. The Command Log shows both your natural language step and the commands Cypress ran.
80+
81+
4. **Cache for speed:** Generated code is cached. Re-running the same test does not re-call the AI model unless the prompt or DOM changes in a way that invalidates the cached code.
82+
83+
5. **Self-heal if needed:** If cached selectors fail (element renamed, attributes changed, etc.), Cypress regenerates code for that step. This 'self-healing' happens automatically on future runs.
84+
85+
6. **Version control (optional):** You can view generated code in the Command Log and save it to your test file for version control. Once saved, the test no longer depends on AI at runtime. This can be ideal for projects that do not want to rely on self-healing or the AI to interpret the prompt on every run.
86+
87+
88+
## Writing Effective Prompts
89+
90+
Prompt clarity determines reliability. Follow these rules:
91+
92+
- **Imperative voice**: Start with an action (click, type, verify).
93+
- **Use absolute URLs**: Use the full URL of the page you want to visit.
94+
- **One action per step**: Avoid chaining multiple actions in one string.
95+
- **Avoid ambiguity**: Specify the action or element explicitly. Wrap specific text, values, or identifiers in quotes to help the AI identify them as exact matches. For example, `click the "Submit" button` is clearer than `click the Submit button`.
96+
- **Include context**: `click the login button in the header` is better than `click login button`.
97+
98+
### Example: Good vs. poor steps
99+
100+
```javascript
101+
// ✅ Good - clear and descriptive
102+
cy.prompt([
103+
'visit https://cloud.cypress.io/users/settings',
104+
'click the "Edit Profile" button',
105+
'type "John Doe" in the name field',
106+
'type "[email protected]" in the email field',
107+
'click the "Save Changes" button',
108+
'verify the success message "Profile updated successfully" appears'
109+
])
110+
111+
// ❌ Poor - vague and error-prone
112+
cy.prompt([
113+
'go to profile',
114+
'click button',
115+
'type name',
116+
'type email',
117+
'save',
118+
'check success'
119+
])
120+
```
121+
122+
### If Cypress cannot interpret a step
123+
124+
If Cypress cannot interpret a step, you'll see a dialog prompting you to refine your prompt. Fill out each step that needs information with a more specific prompt and click **Save** to update the `cy.prompt` code within your test file. The test will then run with the new prompt.
125+
126+
<DocsVideo
127+
src="/img/api/prompt/cy-prompt-need-more-info.mp4"
128+
autoPlay={true}
129+
title="cy.prompt asking for more information when the prompt is not clear"
130+
/>
131+
132+
133+
## What you can do
134+
135+
### Navigate to pages
136+
137+
```javascript
138+
'visit https://example.cypress.io'
139+
'visit /login' // with baseUrl set
140+
```
141+
142+
### Interact with elements
143+
144+
```javascript
145+
'click the login button'
146+
'double click the product image'
147+
'right click the file item'
148+
'type "[email protected]" in the email field'
149+
'clear the username field'
150+
'focus on the search input'
151+
'blur the filter input'
152+
'select "Canada" from the country dropdown'
153+
'check "I agree"'
154+
'uncheck "Send me updates"'
155+
'submit the contact form'
156+
'trigger the "submit" event'
157+
```
158+
159+
### Verify results
160+
161+
```javascript
162+
'expect the notification to contain the text "Email sent"'
163+
'assert the "I agree" checkbox is checked'
164+
'verify an alert with the text "Success" exists'
165+
'ensure that the counter shows 5'
166+
'the heading should be visible'
167+
```
168+
169+
### Wait
170+
171+
```javascript
172+
'wait 5 seconds'
173+
```
174+
175+
176+
## Reliability and control
177+
178+
Everything within `cy.prompt()` is logged in the Cypress Command Log:
179+
180+
- The **prompt** you wrote
181+
- The **Cypress command(s)** generated
182+
183+
You can use the **Get code** button to view the generated Cypress code. This will display the generated code in a dialog where you can preview what Cypress generated from your prompt. You can save the code to your test file, commit it to your version control system, or copy it to your clipboard.
184+
185+
This allows you to use `cy.prompt` as a starting point for your test, but modify it to fit your needs and commit it to your version control system so that you do not rely on the AI for each run to work.
186+
187+
This can be ideal for projects that do not want to rely on self-healing or the AI to interpret the prompt on every run, or for projects that want to commit the generated code to their version control system.
188+
189+
## Setup
190+
191+
### Enable the command
192+
193+
`cy.prompt` is experimental and may change in future releases. Enable the command in your config file:
194+
195+
:::cypress-config-example
196+
197+
```ts
198+
{
199+
e2e: {
200+
experimentalPromptCommand: true,
201+
},
202+
}
203+
```
204+
205+
:::
206+
207+
### Authentication & usage
208+
209+
Because `cy.prompt` uses AI under the hood, it needs to communicate securely with large language models to interpret your prompts. Cypress Cloud helps manage those requests, apply organization-level controls, and track usage in a way that's non-invasive. We never use your prompts to train AI models, and you can turn AI features off at any time. `cy.prompt` is currently available on any of our [Cypress Cloud plan types](https://www.cypress.io/pricing).
210+
211+
**To use `cy.prompt`, you must either:**
212+
213+
- Log into Cypress Cloud
214+
- Or run with `--record` and a valid `--key`. See [instructions](/cloud/get-started/setup).
215+
216+
**If you don't have a Cypress Cloud account, sign up to start your 2 week free trial.**
217+
218+
<Btn
219+
label="Sign up ➜"
220+
variant="indigo-dark"
221+
className="mr-1"
222+
href="https://cloud.cypress.io/signup"
223+
/>
224+
<Btn
225+
label="See a demo"
226+
icon="action-play-small"
227+
className="mr-1"
228+
href="https://www.youtube.com/watch?v=vFLShoCM8pA"
229+
/>
230+
<Btn
231+
label=" Explore an example project"
232+
icon="technology-terminal-log"
233+
href="https://cloud.cypress.io/projects/7s5okt"
234+
/>
235+
236+
## Examples
237+
238+
### Login flow
239+
240+
```javascript
241+
const password = Cypress.env('adminPassword')
242+
243+
cy.prompt([
244+
'visit the login page',
245+
'type "[email protected]" in the email field',
246+
'type ${password} in the password field',
247+
'click the login button',
248+
'verify we are redirected to the dashboard'
249+
], {
250+
excludeFromAI: ['password']
251+
})
252+
```
253+
254+
### E-commerce checkout
255+
256+
```javascript
257+
cy.prompt([
258+
'visit https://example.com/products',
259+
'search for "wireless headphones"',
260+
'click on the first search result',
261+
'click the "Add to Cart" button',
262+
'verify the cart icon shows 1 item',
263+
'click the cart icon',
264+
'click the "Proceed to Checkout" button',
265+
'fill in shipping information',
266+
'select standard shipping',
267+
'enter credit card details',
268+
'click the "Place Order" button',
269+
'verify the order confirmation page loads'
270+
])
271+
```
272+
273+
### Mixed with traditional Cypress
274+
275+
```javascript
276+
const electronicsCount = 25
277+
278+
// Confirm the UI works in desktop view
279+
cy.viewport(1024, 768)
280+
cy.visit(`${Cypress.env('stagingUrl')}/products`)
281+
cy.prompt([
282+
'filter by category "Electronics"',
283+
'sort by price high to low',
284+
`verify the product count is ${electronicsCount}`,
285+
'verify the sort indicator is "Price: High to Low"'
286+
])
287+
288+
// Confirm the UI works in mobile view
289+
cy.viewport(400, 600)
290+
cy.visit(`${Cypress.env('stagingUrl')}/products`)
291+
cy.prompt([
292+
'filter by category "Electronics"',
293+
'sort by price high to low',
294+
`verify the product count is ${electronicsCount}`,
295+
'verify the sort indicator is "Price: High to Low"'
296+
])
297+
```
298+
299+
Or to further clean up the `cy.prompt` call:
300+
301+
```javascript
302+
const electronicsCount = 25
303+
const electronicsFilterPrompt = [
304+
'filter by category "Electronics"',
305+
'sort by price high to low',
306+
`verify the product count is ${electronicsCount}`,
307+
'verify the sort indicator is "Price: High to Low"'
308+
]
309+
310+
// Confirm the UI works in desktop view
311+
cy.viewport(1024, 768)
312+
cy.visit(`${Cypress.env('stagingUrl')}/products`)
313+
cy.prompt(electronicsFilterPrompt)
314+
315+
// Confirm the UI works in mobile view
316+
cy.viewport(400, 600)
317+
cy.visit(`${Cypress.env('stagingUrl')}/products`)
318+
cy.prompt(electronicsFilterPrompt)
319+
```
320+
321+
## Limitations
322+
323+
| Limitation | Details |
324+
|------------|---------|
325+
| Browser Support | Chromium-based browsers only (Chrome, Edge, Electron) |
326+
| Test Type | E2E tests only (component testing not yet supported) |
327+
| Authentication | Requires Cypress Cloud account or valid record key |
328+
| Command Coverage | Not all Cypress APIs supported - see [Supported Actions](#supported-actions) |
329+
330+
## Pricing & availability
331+
332+
During the experimental release, access will be provided at no additional charge. While certain built-in limits on prompt calls will apply, these are not intended to block reasonable usage. Our objective is to collect feedback and utilize this information to guide future development of the feature. Please note that pricing and usage limitations are subject to future adjustments, and we commit to keeping you informed of any such changes.
333+
334+
### Privacy & security
335+
336+
For detailed information about how Cypress protects your data and manages AI model security, see our [Security & Compliance page](https://www.cypress.io/security).
337+
338+
### Disabling AI features
339+
340+
AI capabilities, including `cy.prompt`, are enabled by default for all users on any Cloud plan. Organization admins and owners can enable and disable the AI capabilities for their entire organization from their organization settings. For more information, see [our FAQ](/cloud/faq#are-all-cloud-ai-capabilities-enabled-by-default-how-can-i-turn-them-off).
341+
342+
## History
343+
344+
| Version | Changes |
345+
| --------- | ------------------------ |
346+
| [15.0.0](/app/references/changelog) | Introduced experimental `cy.prompt` command |
347+
348+
---
349+
350+
## See also
351+
352+
- [Cypress Studio](/app/guides/cypress-studio)

‎src/css/custom.scss‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,6 +293,18 @@ html[data-theme='dark'] {
293293
}
294294
}
295295

296+
.alert.alert--secondary {
297+
background-color: var(--ifm-color-indigo-50);
298+
color: var(--ifm-color-indigo-1000);
299+
--ifm-alert-border-color: var(--ifm-color-indigo-400);
300+
301+
[data-theme='dark'] & {
302+
background-color: var(--ifm-color-indigo-1000);
303+
color: var(--ifm-color-indigo-50);
304+
--ifm-alert-border-color: var(--ifm-color-indigo-800);
305+
}
306+
}
307+
296308
div[class^='announcementBar'] {
297309
font-size: 1rem;
298310
font-weight: var(--ifm-font-weight-semibold);

‎static/img/api/prompt/cy-prompt-demo.mp4‎

936 KB
Binary file not shown.

‎static/img/api/prompt/cy-prompt-need-more-info.mp4‎

315 KB
Binary file not shown.

0 commit comments

Comments
 (0)