Getting Started with Cypress Studio
Record browser interactions as Cypress tests, review the generated commands, and add assertions that verify the behavior your users rely on.
Cypress Studio records selected interactions in your application and turns them into commands in a Cypress end-to-end (E2E) test. You can use it to create a test or extend an existing one. The generated commands are a starting point: review them and add assertions that check the behavior that matters.
Basic Studio recording and manual editing do not require Cypress Cloud. Studio requires internet access and sourcemaps. AI assertion recommendations are an optional feature that requires a Cypress Cloud account and a linked project. See the Cypress Studio guide.
1. Decide whether E2E testing fits the test
Studio is for authoring E2E tests. Choose E2E when you want to exercise a user journey through the application in a browser, such as signing in or submitting a form. Choose component testing when you want to mount an individual component and test its behavior in isolation. The Cypress App setup guide explains the distinction and walks through the first launch.
2. Install Cypress and open the App
Install Cypress in your project using your package manager, then open it from the project root. If Cypress is already installed, go straight to the open command.
# npm
npm install --save-dev cypress
npx cypress open
# Yarn
# yarn add --dev cypress
# yarn cypress open
# pnpm
# pnpm add --save-dev cypress
# pnpm cypress open
# Bun
# bun add --dev cypress
# bunx cypress openOn first launch, the Launchpad guides you through selecting a test type, generating configuration, and choosing a browser. Choose E2E for a user-journey test. Cypress creates the project files it needs; review the generated changes before continuing. Once setup is complete, open mode is the interactive local workflow for running specs, inspecting the app, using Studio, and debugging.
You can add a convenient npm script to package.json:
{
"scripts": {
"cy:open": "cypress open"
}
}Then run npm run cy:open. Avoid naming the script cypress, which can conflict with Cypress CLI commands in Yarn.
3. Create or open an E2E spec
Start your application in a separate terminal so Cypress can visit it. In the Cypress App, create or select an E2E spec and run it. The first-test guide shows the basic sequence: visit the app, query an element, interact with it, and assert the result. See Testing Your App and Why Cypress?.
A useful test structure is:
it('adds a todo', () => {
cy.visit('http://localhost:3000')
cy.get('[data-cy="new-todo"]').type('write tests{enter}')
cy.get('[data-cy="todos"]').should('have.length', 1)
})Use the real local URL and selectors from your app. This example demonstrates the shape of a test; Studio can help author the interactions, but you are responsible for choosing meaningful outcomes to assert.
4. Open Studio to create or extend a test
- To create a test: use the spec or suite’s New Test control. Give the test a descriptive name and enter the URL to visit. Studio writes a
cy.visit()command as the starting point. - To extend a test: run the spec, find the test in the Command Log, hover over it, and choose Edit in Studio. Studio runs the test through its last command; new recorded actions and assertions are appended there.
- Record: interact with the app in the browser as a user would. Cypress documents recording clicks, typing, checking and unchecking controls, and selecting options.
- Pause when inspecting: pause recording before using DevTools to inspect or debug, then resume recording when ready.
- Review and save: inspect the commands Studio generated, edit them inline if needed, and add assertions for the expected result.
Studio also provides undo, redo, and reset controls. Its documented selector preference order is data-cy, data-test, data-testid, data-qa, name, id, class, tag, attributes, and finally nth-child. Stable test-specific attributes such as data-cy generally make intent clearer than position-based selectors. Cypress documents Cypress.ElementSelector for setting project-specific selector priorities.
5. Review the generated test like production code
Recording captures actions, not the intent behind them. After recording, read the spec and confirm that it describes a stable, valuable user flow.
- Keep useful setup: arrange required application state deliberately. Avoid depending on data left behind by a previous run.
- Check every action: confirm Studio selected the intended element and produced the expected command.
- Add assertions: assert the result a user should observe, such as a confirmation message, a changed URL, or an updated item count. An action that completes without an assertion can pass even if the application behavior is wrong.
- Prefer stable selectors: use test attributes or meaningful accessible selectors when available. Review selectors that depend on CSS classes, broad attributes, or
nth-child; they can break when markup changes. - Re-run the spec: verify the saved test from a clean, understood starting state. Fix the test or setup if the behavior is inconsistent.
A practical mental model is: set up state, take an action, assert the resulting state. Studio assists with the action step; the developer still defines setup and what counts as success.
6. Studio and Studio AI: what requires Cloud?
| Capability | Basic Studio | Studio AI |
|---|---|---|
| Record interactions | Yes | Yes |
| Add assertions manually | Yes | Yes |
| Edit code inline; undo, redo, reset | Yes | Yes |
| AI assertion recommendations | No | Yes |
| Cypress Cloud account and linked project | Not required | Required |
| Internet access and sourcemaps | Required | Required |
Cloud recorded-run history and analytics are useful when you want to review runs beyond local interactive development. They are separate from the basic ability to use Studio. Cypress’s current guide describes a limited opportunity to try AI recommendations before sign-in and current Cloud plan/trial terms; those offers can change, so check the current guide rather than relying on a remembered limit.
7. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Studio reports that it cannot load or edit the test | Sourcemaps are missing or unavailable. | Check the app and test build configuration for sourcemaps. Cypress enables them by default in most configurations; use the official Studio guide if your setup needs explicit configuration. |
| Studio does not open or its features fail to load | Studio requires internet access. | Check network access, proxy or firewall restrictions, and retry in the Cypress App. |
| Studio AI recommendations are unavailable | AI recommendations need Cypress Cloud and a linked project; basic Studio does not. | For AI recommendations, connect the project to Cloud as described in the Studio panel and documentation. To keep recording manually, use basic Studio without Cloud. |
| The generated selector breaks after a layout change | The selector may rely on a class, generic attribute, or positional nth-child. |
Replace it with a stable test attribute or another selector that identifies the intended control. Set project selector priorities with Cypress.ElementSelector if needed. |
| A recorded test passes without checking the outcome | Interactions alone do not establish that the expected behavior occurred. | Add an assertion after the action and confirm it fails when the expected state is absent. |
| Recording includes accidental clicks or typing | Recording was active during inspection or unrelated browsing. | Undo or edit the unwanted commands. Pause Studio before using DevTools, then resume when you are ready to capture app interactions. |
| The test starts from an unexpected state | The application or test data was not reset consistently. | Make setup explicit and reproducible, and run the spec again from that known state. |
8. Performance, reliability, and cost
Studio is an authoring workflow in the Cypress App, not a separate test runtime. The time spent recording is not a substitute for measuring the test itself: generated commands still need to run reliably in the browsers and environments your team uses. Keep setup repeatable, use stable selectors, and assert observable outcomes. Avoid adding arbitrary timing delays just to make a recorded test pass; diagnose why the expected state is not ready.
For local development, Cypress open mode supports interactive runs and debugging. Cypress Cloud is optional for basic Studio and is relevant for recorded-run history and analytics; Studio AI recommendations require a linked Cloud project. Check Cypress’s current plan details for any Cloud cost or AI usage terms before adopting those features. The basic recording path does not require a Cloud subscription.
Or skip the browser setup
If your goal is a screenshot of a page for review or documentation rather than authoring an E2E test, ScreenshotNeo can return an image or PDF from one API request. It complements Cypress: a screenshot does not replace interaction tests or assertions. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Can I use Studio to create a test from scratch?
Yes. Start from the spec or suite’s New Test control, name the test, and provide the page URL Studio should visit.
Does Studio record every browser action?
No. Cypress documents recording clicks, typing, checking, unchecking, and selecting. Review the resulting test and add any needed setup or assertions yourself.
Can Studio help with component testing?
The Studio guide describes generating and extending E2E tests. For isolated component behavior, use Cypress Component Testing and its component-testing workflow.
Where can I inspect what happened during a run?
Use the Cypress App’s Command Log and snapshots in open mode to inspect commands and application state. See the open mode guide.
