Add Cypress to an Angular Workflow With Nx

To add Cypress to an existing Angular app in an Nx workspace, first align the Nx Cypress plugin with the workspace, then choose the kind of behavior to test. Use end-to-end (E2E) tests for complete user flows through a running application. Use component tests for Angular components rendered by Cypress’s component-testing environment. These paths have different generators, targets, and server behavior.

1. Check the workspace and install the Nx Cypress plugin

From the workspace root, check the installed Nx version and package manager, then add the matching plugin:

nx report
nx add @nx/cypress

Nx recommends keeping Nx package versions in sync. Its current Cypress guide lists support for Cypress versions >=13 <16; check the live Nx documentation and your workspace’s package constraints before changing Cypress versions. The generator installs a supported version when it scaffolds configuration. Avoid independently upgrading one Nx package to a version that does not match the rest of the workspace.

Confirm the Angular application’s Nx project name. Depending on the workspace, project configuration may live in a project.json, the root package.json, or package metadata. Use that project name in the commands below.

2. Choose E2E or component testing

Question	E2E	Angular component testing
What runs in Cypress?	The application through its served or deployed URL	An Angular component in Cypress’s component-test environment
Nx configuration	`nx g @nx/cypress:configuration`	`nx g @nx/angular:cypress-component-configuration`
Server/build arrangement	Use an Nx dev-server target or provide a base URL	Cypress starts its component dev server; Nx needs a suitable Angular build target for project context
Typical Nx task	`nx e2e app-name`	`nx component-test project-name`
Good fit	Navigation, routing, and flows spanning the application	Rendering and interactions centered on a component

The choice depends on what you need to verify. Adding one mode does not automatically configure the other.

3. Configure Cypress E2E for an existing Angular app

Generate Cypress configuration for the existing Nx app:

nx g @nx/cypress:configuration --project=your-app-name

Replace your-app-name with the Nx project name. This generator configures that project; it does not create a separate E2E project. Nx commonly creates an e2e target that runs Cypress and starts the app using its development-server target.

When the app is served elsewhere

If the Cypress target should not start the application, provide the URL it should test:

nx g @nx/cypress:configuration \
  --project=your-app-name \
  --baseUrl=http://localhost:4200

Make sure the URL points to the intended version of the app and is reachable before running Cypress. Nx requires a base URL when the configuration has neither a base URL nor a dev-server target.

Run an E2E test

Use the target generated in your workspace; the common default is:

nx e2e your-app-name

A typical target uses the @nx/cypress:cypress executor, the Cypress configuration file, testingType: "e2e", and the app’s devServerTarget. Your generated file may differ by Nx version or workspace configuration. Inspect the project target rather than replacing it with a template that may omit workspace-specific settings.

For CI, the target can use a static-serving target where appropriate. Nx also documents an advanced ciWebServerCommand setup for E2E test splitting; preserve the Cypress preset’s setupNodeEvents behavior if you customize it.

4. Configure Angular component testing

For a component test target attached to an Angular app or library, use the Angular generator:

nx g @nx/angular:cypress-component-configuration --project=my-angular-project

The generator adds a Cypress component-test configuration prepared for Nx. Nx’s current Cypress plugin guide lists Cypress >=13 <16; the Angular generator reference also documents an older minimum of 10.7.0. Treat the plugin’s current supported range and your installed Nx version as the practical compatibility check, rather than installing an old Cypress version just because it meets that historical minimum.

Check the build target

Nx may infer a build target from the project graph. If it cannot resolve one unambiguously, specify an eligible target explicitly:

nx g @nx/angular:cypress-component-configuration \
  --project=my-angular-project \
  --build-target=my-angular-app:build

The build target supplies project/build context, including the assets, scripts, and styles relevant to the component. Nx documents targets using @nx/angular:webpack-browser or @angular-devkit/build-angular:browser. A library’s target can belong to an application that consumes the library. Confirm that the named project and builder exist in your workspace before using the example.

The component-test target should set skipServe: true. Cypress provides its own component dev server, so Nx should not start the build target as a separate server. The Angular component-configuration generator sets this automatically in the documented setup; check the generated target if your workspace version behaves differently.

Run component tests

nx component-test my-angular-project

To generate starter test files for existing components, use the generator’s --generate-tests option when configuring component testing. Nx documents the generated component tests with the .cy.ts suffix, typically alongside the component.

5. Inspect inferred Nx targets

Nx can infer Cypress tasks from recognized Cypress configuration files—cypress.config.js, .ts, .mjs, or .cjs—in a directory containing a package.json or project.json. Documented defaults include e2e, component-test, and open-cypress; CI uses e2e-ci. Plugin options in nx.json can change target names, so treat these as defaults, not guarantees.

Inspect the actual project configuration and inferred targets before troubleshooting or scripting against a target name:

nx show project your-app-name --web

In Nx Console, you can inspect the project and its available tasks as well. This is especially useful when the workspace has customized plugin options, multiple Cypress configurations, or project configuration in nonstandard locations.

6. Add the tests that match the target

Example E2E spec

Place a spec in the E2E project’s configured spec directory. The test should visit the running app by its configured base URL and assert user-visible behavior. Adapt the route and accessible name to the app:

describe('home page', () => {
  it('shows the primary navigation', () => {
    cy.visit('/');
    cy.findByRole('navigation', { name: /primary/i }).should('be.visible');
  });
});

This example uses Cypress Testing Library’s findByRole query. If that package is not installed and configured in the workspace, use Cypress’s built-in query instead, for example cy.get('nav').should('be.visible'), or add the query library according to its own setup instructions.

Example Angular component spec

Component specs use Cypress Angular mounting support and the project’s component-test setup. Adapt the import paths and component inputs:

import { mount } from 'cypress/angular';
import { GreetingComponent } from './greeting.component';

describe('GreetingComponent', () => {
  it('renders the supplied name', () => {
    mount(GreetingComponent, {
      componentProperties: { name: 'Ada' },
    });

    cy.contains('Ada').should('be.visible');
  });
});

This assumes the component exposes a name input and the generated Cypress support setup handles the Angular environment. If your component depends on providers, routing, or other imports, configure those in the mount options or the workspace’s shared component-test setup.

7. Run, cache, and split tests in CI

Run the generated Nx target locally before adding it to CI. Nx documents Cypress E2E and component-test tasks as cacheable and as tracking Cypress screenshot and video outputs. Check the target’s inputs, outputs, and cache configuration in your workspace if results appear stale or artifacts are missing.

Nx can infer CI tasks that split tests by file when configured. Component-test CI splitting is documented as available since Nx 21.6.1, so confirm the installed Nx version before relying on it. E2E splitting also requires CI-specific configuration; it is not enabled merely by installing the plugin. Start with the generated target, then follow the Nx guide for the installed version if CI duration warrants splitting.

8. Common problems and fixes

Symptom	Likely cause	What to check or change
Plugin installation reports incompatible versions	Nx packages are out of sync or the Cypress version is outside the supported range	Compare `nx report` and package versions; align Nx packages and use a Cypress version supported by the installed plugin.
No `e2e` or `component-test` target appears	The config file was not discovered, project metadata is elsewhere, or the workspace customized inferred target names	Confirm the config filename and that its directory has a `project.json` or `package.json`; inspect `nx show project ... --web` and `nx.json`.
E2E test cannot connect or reports a missing base URL	No dev-server target or base URL is configured, or the app is not running at the configured URL	Inspect the E2E target and Cypress config; start the app or configure the correct `baseUrl`/`devServerTarget`.
Component test cannot resolve a build target	Nx could not infer a suitable Angular build target, or the specified project/target name is wrong	Inspect the project graph and available targets; pass the consuming app’s eligible build target with `--build-target` when needed.
Component target tries to serve the app separately	`skipServe` is missing or false	Set `skipServe: true` for the component-test target; Cypress supplies the component dev server.
Component fails during mount	Required providers, imports, or component inputs were not supplied	Include the component’s required setup in the mount options or shared Cypress component configuration.
Tests pass locally but fail in CI	CI may use a different URL, serving target, environment, or Nx/Cypress version	Compare the generated target, environment variables, and served app version; use the CI-specific target and inspect its logs.
Cached result or missing video/screenshot surprises the team	Task inputs or outputs do not match expectations, or the task is cached	Inspect Nx target caching and declared artifact outputs; rerun without cache when diagnosing, then correct the target configuration if needed.

9. Performance, reliability, and cost notes

Keep E2E coverage focused on flows that cross meaningful application boundaries, and use component tests for behavior that can be exercised around a component. This is a scope choice, not a promise that one mode will always run faster. Nx caching can avoid repeating eligible tasks when their declared inputs match. CI splitting can distribute test files when configured and supported by the workspace version.

Reliability depends on testing the intended app build at a reachable URL, supplying the component’s required Angular context, and keeping plugin and Nx versions compatible. The dossier does not establish a universal runtime, failure rate, or cost for Cypress in an Nx workspace; those depend on the project and CI environment.

Or skip the browser setup

If your workflow also needs page screenshots, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It is separate from Cypress and does not replace application E2E or component tests. One GET request captures a URL; 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.webp

import 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 Bun.write('shot.webp', res);

Replace YOUR_API_KEY with your key. These examples save the returned image bytes; check the response status in production before treating a response as an image.

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 shots a month with no card. Paid plans start at $5 for 3,000; all features are available on every plan.

FAQ

Does adding the Cypress plugin create a separate E2E project?

No. The E2E configuration generator configures the project you name. Create a separate project independently if your workspace structure calls for one.

Can one workspace use both E2E and component tests?

Yes. They are separate testing modes with different configuration and execution needs; add the corresponding configuration and targets for each.

Does Cypress component testing use the app’s dev server?

Nx’s Angular component setup uses Cypress’s component dev server and sets skipServe: true. Nx still uses the configured build target to prepare project context.

Where should component test files go?

The Angular generator documents .cy.ts files beside the component. Follow the spec pattern and support-file paths in the configuration generated for your workspace.