Migrate from Protractor to Cypress in stages: add Cypress to your Angular workspace, port representative tests by their behavior, and run both suites side by side until Cypress coverage is dependable. Protractor reached end-of-life in August 2023, so existing users should plan a transition; the Protractor project website discourages new adoption and recommends migrating (Protractor project website).
Why move from Protractor to Cypress?
Protractor is deprecated and reached end-of-life in August 2023, according to the Protractor project website. Separately, Cypress’s migration guide notes that Protractor stopped being included in new Angular projects as of Angular 12. The Angular default change and Protractor’s end-of-life are distinct milestones.
As an Amazon Associate I earn from qualifying purchases.
A migration is not a command that converts an entire suite. Protractor and Cypress use different test interaction models, so the practical work is to preserve what each test verifies while rewriting how it finds elements, interacts with the page, waits, and asserts. Cypress’s migration guide documents setup and common command translations.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Inventory the suite before changing its runner
Make a simple map of the current coverage before altering workspace configuration. This is an implementation step, not a Cypress-generated conversion: the goal is to know what behavior must survive the move.
- List user journeys covered by the suite and the important assertions each journey makes.
- Identify shared page objects, helper functions, custom locators, and browser setup.
- Mark uses of
waitForAngular(), fixed delays, and other explicit waits; note what each wait is intended to ensure. - Record the current Angular CLI project, serve target, and CI commands so the new runner can use the right application and environment.
- Choose a small, representative set of tests to port first, including interactions and asynchronous UI behavior.
Add Cypress to an Angular workspace
Recommended: use the Angular schematic
Cypress recommends adding its Angular schematic with:
ng add @cypress/schematicAccording to the Cypress guide, the schematic installs Cypress, adds open and run scripts, and scaffolds base Cypress files and directories. It can also prompt to remove Protractor and configure Angular CLI’s default ng e2e target to use Cypress. Review those optional changes rather than accepting them automatically if you need Protractor during a staged migration.
Manual installation
The Cypress guide also documents manual package-manager installation. With this approach, ensure a separate process serves the Angular application while Cypress runs against it. The guide gives concurrently as one way to start the app and Cypress together; it is an optional helper, not a Cypress requirement. Because workspace scripts and serve targets differ, use the commands appropriate to your Angular project rather than copying a script without checking what it starts.
Translate tests by intent, not by search-and-replace
Protractor tests commonly use Selenium/WebDriver-style element operations. Cypress uses chained queries and commands. These guide examples show common starting-point translations; custom locators, helpers, and assertions still need a behavior-level review.
| Protractor pattern | Cypress pattern |
|---|---|
element(by.css('#email-field')) |
cy.get('#email-field') |
.sendKeys('text') |
.type('text') |
| Click a checkbox | .check() |
| Uncheck a checkbox | .uncheck() |
| Select an option | .select('value') |
| Move an element into view | .scrollIntoView() |
| Find text within a selector | A Cypress query such as .contains(...) |
A compact interaction example, based on the Cypress guide’s mappings:
// Protractor
element(by.css('input')).sendKeys('my text')
element.all(by.css('[type="checkbox"]')).first().click()
// Cypress
cy.get('input').type('my text')
cy.get('[type="checkbox"]').first().check()After an interaction, assert the resulting application state that matters to the user. Do not assume a translated click or typing command alone preserves the original test’s intent. Cypress also points to Testing Library commands as an option for selecting elements.
Replace implicit waits with retryable conditions
Protractor suites may rely on waitForAngular() or arbitrary timeouts. Cypress retries DOM queries and waits for an element to become actionable, subject to its configured defaultCommandTimeout. In the Cypress guide’s approach, tests assert the expected rendered state instead of explicitly waiting for Angular.
For each old wait, ask what it was protecting against: a result appearing, a button becoming enabled, a route rendering, or some other observable condition. Prefer a retryable query followed by a specific assertion when that is the condition the test needs. Do not mechanically replace every delay with cy.wait(number); a fixed pause does not express the condition and can make a test unnecessarily slow or still unreliable. Cypress’s retry behavior is not a claim that every kind of asynchronous work in an application is automatically handled.
Can Protractor and Cypress coexist in the same app?
Yes. Cypress says teams do not have to replace all tests immediately and documents keeping Protractor tests in Angular CLI’s e2e directory while Cypress specs live in a sibling cypress folder. This lets a team introduce Cypress without making an all-at-once runner switch.
A low-disruption rollout
- Keep the existing Protractor suite and its CI job running while Cypress is introduced.
- Port one stable, valuable journey and check that its Cypress assertions cover the same user-visible behavior.
- Run the Cypress spec locally and in CI against the intended application environment.
- Compare the coverage and failure behavior of the new spec with the Protractor test it is meant to replace.
- Repeat for additional journeys; retire a Protractor test only after its Cypress counterpart is reliable in your team’s environment.
This sequence is a practical rollout recommendation built on the documented coexistence model; project-specific helpers, browsers, and CI configuration still determine the details.
Run Cypress locally and in CI
With the Angular schematic, the Cypress guide documents these commands:
Free tools Windows power users keep installed
One-click scans. No signup required.
ng e2eng run {project}:cypress-openng run {project}:cypress-run
Replace {project} with the Angular CLI project name in your workspace. The guide also documents browser selection with --browser or a configured default browser. Confirm that the selected browser is available in the environment where the command runs.
For manual setup, the guide shows example cy:open and cy:run scripts that start the application and Cypress together. Adapt them to your serve command and whether the app is already running in CI; avoid starting a second server against a port already in use.
Optional recording and parallelization
If CI scaling or debugging needs justify it, Cypress’s guide shows running Cypress with --record --parallel and describes schematic options for parallel, record, and a recording key. It points to Cypress Cloud for recorded runs and describes Test Replay as a debugging capability for recorded runs. Recording and parallelization are optional workflow choices: evaluate the additional service configuration against your CI needs rather than making them a prerequisite for migration.
Troubleshooting migration problems
- The Cypress command cannot reach the app: In a manual setup, verify that the Angular server is running and that Cypress targets the correct address. If a script starts both processes, check that it uses the workspace’s actual serve command.
ng e2estill invokes Protractor: The schematic can optionally redirect Angular CLI’s default E2E target. Check whether that option was selected and inspect the workspace target before assuming the command changed.- A translated interaction fails: Check whether the selector still identifies the intended element and whether the original locator or helper encoded additional behavior. The documented mappings are examples, not one-to-one replacements for every custom operation.
- A test is flaky after removing a wait: Identify the observable state the old wait was intended to protect. Use a retryable query and assertion for that state where possible, rather than inserting an arbitrary fixed delay.
- A browser run works locally but not in CI: Check the CI command, selected browser, application serve process, and project-specific environment. The Cypress guide documents browser selection, but the correct browser and setup depend on what the CI environment provides.
- Recorded parallel runs do not start as expected: Confirm that recording is configured, the required recording key is available, and the run command includes the intended options. These are optional recorded-run settings, not required for ordinary local Cypress execution.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a replacement for migrating or running E2E tests. It can be useful when a workflow also needs a clean screenshot of a page: cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For example, this cURL request captures a website screenshot. See the ScreenshotNeo documentation for API details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpLearn about ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does Cypress convert a Protractor suite automatically?
The documented migration approach supplies setup guidance and command mappings; custom locators, helpers, and test assertions need to be reviewed and rewritten for their intended behavior.
Do I have to remove Protractor when adding Cypress?
No. Cypress documents running the suites side by side during a gradual migration.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
