Playwright Setup and Fundamentals Compared to Cypress

1. Playwright and Cypress: two paths to the same goal

Anyone setting up a new frontend project to guard against regressions today almost inevitably runs into two names: Cypress and Playwright. Both frameworks solve the same core task, simulating real user interactions in a real browser, and cover far more ground than a pure PHPUnit test on the class level ever could. The difference is not in the basic idea but in the architecture underneath: how tests control the browser, which browser engines are supported, and how teams diagnose failures in the CI pipeline.

For Magento and Hyva projects this decision matters in particular, because storefronts with Alpine.js interactions, cart updates and checkout flows move through many asynchronous states that a unit test never touches. This article walks through installing Playwright, the most important configuration options and a first real test against a storefront, before a direct comparison with Cypress helps at the end with the framework choice.

2. Installing Playwright: npm init playwright@latest in detail

Installing Playwright starts with a single command: npm init playwright@latest. The CLI tool interactively asks whether to use TypeScript or JavaScript, what the test directory should be called (default: tests), whether to add a GitHub Actions workflow file, and whether to download the browser binaries right away. Unlike Cypress, which opens a graphical setup screen on first launch, Playwright stays entirely in the terminal and generates all files without a manual intermediate step.

Once finished, a ready to run scaffold is in place: playwright.config.ts at the project root, a tests folder with a sample test, a tests-examples folder with instructional reference tests, and the matching package.json scripts. The command npx playwright install additionally downloads the three browser engines Chromium, Firefox and WebKit as standalone binaries, completely independent of any locally installed Chrome or Firefox. That makes CI environments deterministic, because every pipeline uses exactly the same browser version instead of whatever happens to be preinstalled on the runner.

# Install Playwright in a new or existing Node.js project
npm init playwright@latest

# CLI prompts (interactive):
#   - TypeScript or JavaScript?          -> TypeScript
#   - Tests folder name?                 -> tests
#   - Add a GitHub Actions workflow?     -> Yes
#   - Install Playwright browsers now?   -> Yes

# Download all three browser engines as standalone binaries
npx playwright install --with-deps

3. Anatomy of playwright.config.ts

The central configuration file playwright.config.ts is a single TypeScript object with clearly separated responsibilities. The projects array defines which browser engines the same test suite runs against, usually one entry each for Chromium, Firefox and WebKit with the matching devices presets from @playwright/test. The use block sets global defaults such as baseURL, trace, screenshot and video, which every project inherits and can override individually.

Reporters are configured through the reporter field, typically a combination of html for local review and github or junit for CI integration. On top of that, timeout, retries and fullyParallel control the runtime behavior of the whole suite from a single place. Cypress has a comparable concept in cypress.config.ts, but it lacks a native projects array for multi browser runs. Browser variants in Cypress instead need separate CLI invocations with the --browser flag.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  reporter: [['html'], ['github']],

  use: {
    baseURL: 'https://storefront.mironsoft-shop.test',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  // Same test suite runs against all three engines
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

4. Multi browser by default: Chromium, Firefox and WebKit

The structurally biggest difference between the two frameworks shows up in browser support. Playwright ships with Chromium, Firefox and WebKit as three fully supported engines from a single install, and WebKit is the engine behind Safari, the only practical way to test Safari rendering without a real Apple device in CI. All three engines run as standalone browser builds that Playwright itself manages and patches, independent of operating system updates.

Cypress, on the other hand, has historically focused on the Chromium family: Chrome, Edge and its own Electron runtime run stably with a full feature set. Firefox support has existed since Cypress 4, but is considered less mature and does not cover every command identically. Cypress offers no WebKit or Safari engine at all, and an experimental WebKit package was discontinued again in 2023. For projects that seriously need to cover Safari users, for instance because a relevant share of Magento traffic comes from iOS devices, Playwright is therefore often the more obvious choice.

5. Locators, auto waiting and isolated browser contexts

Playwright controls browsers from the outside via the Chrome DevTools Protocol or the cross browser WebDriver BiDi protocol, instead of embedding itself directly into the browser process like Cypress does. That enables real browser contexts: every test can run in a fresh, isolated context with its own cookies, its own local storage and its own session, comparable to a brand new incognito window, without needing to spin up a completely new browser process for it.

Playwright's locator API automatically waits until an element is visible, enabled and stable before an action is performed, with no explicit waitFor calls needed in the test code. Cypress follows a similar underlying idea with automatic retries on assertions, but runs as a script inside the browser itself, which has traditionally made cross origin navigation harder. Since cy.origin(), Cypress also supports multi domain flows, though the detour through an explicit command still feels noticeable next to Playwright's seamless page.goto() navigation across arbitrary domains.

6. First test: add to cart flow in the Hyva storefront

A realistic first test checks the central conversion path of a Magento store: open a product, add it to the cart, and verify the updated cart display. In Playwright, such a test starts with page.goto() on the relative product URL, building on the baseURL from the configuration. Elements are targeted through page.getByRole() or page.getByTestId(), semantic locators that are more resilient against CSS refactors than classic CSS class selectors.

After clicking the add to cart button, expect(locator).toBeVisible() or toHaveText() verifies that the mini cart counter in the Hyva header actually updated, including automatic waiting for the Alpine.js driven UI update. The full test runs with npx playwright test add-to-cart.spec.ts against every browser project defined in the configuration at once, without the test code itself needing to know anything about the multi browser execution.

import { test, expect } from '@playwright/test';

test.describe('Storefront add-to-cart flow', () => {
  test('adds a product and updates the mini cart', async ({ page }) => {
    // baseURL comes from playwright.config.ts, no need to repeat the host
    await page.goto('/catalog/product/example-hoodie.html');

    // Semantic locator instead of a brittle CSS class selector
    await page.getByRole('button', { name: 'Add to Cart' }).click();

    // Auto-waits for the Alpine.js driven mini-cart update
    const miniCartCount = page.getByTestId('minicart-counter');
    await expect(miniCartCount).toHaveText('1');
    await expect(page.getByText('You added the item to your cart')).toBeVisible();
  });
});

7. Trace Viewer and UI Mode: built in debugging

A failing test in the CI pipeline is hard to diagnose without good context. Playwright's Trace Viewer, when set to trace: 'on-first-retry', records a complete capture of the test run: DOM snapshots before and after every action, network requests, console logs and screenshots, all packed into a single .zip file. Running npx playwright show-trace trace.zip opens a timeline that can be navigated frame by frame, with no need to rerun the test locally.

For local development, UI Mode (npx playwright test --ui) provides an interactive interface with a watch mode, a timeline and a pick locator tool. Cypress was one of the pioneers in this area with its Test Runner and time travel debugging, and it also offers an excellent local developer experience. The decisive difference shows up in the CI case: Cypress traces at this level of detail require Cypress Cloud as a paid service, while Playwright's Trace Viewer works entirely locally and for free.

8. Parallelization and the worker model

Playwright distributes test files across multiple worker processes by default, with the count based on available CPU cores and controllable through workers in the configuration or the CLI flag --workers=4. With fullyParallel: true, even individual tests within the same file can run in parallel, not just across files. For large CI pipelines, Playwright additionally supports sharding via --shard=1/4, which splits a test suite across several CI machines, with each machine handling only its own share.

Cypress runs tests serially within a single browser instance by default. Real parallelization across multiple machines requires Cypress Cloud or third party orchestration that manually distributes test files across CI runners. For teams with a limited budget, that means Playwright's worker and sharding model delivers free, built in parallelization, while comparable Cypress speed usually requires additional license costs or homegrown infrastructure.

{
  "scripts": {
    "test": "playwright test",
    "test:ui": "playwright test --ui",
    "test:debug": "playwright test --debug",
    "test:report": "playwright show-report",
    "test:chromium": "playwright test --project=chromium"
  }
}

9. Cypress or Playwright: a decision framework for new projects

The choice between Cypress and Playwright rarely comes down to a single criterion, but rather to a combination of team skillset, browser coverage needs and CI budget. Teams with pure JavaScript/TypeScript experience and a focus on Chrome users are often productive faster with Cypress, because its documentation and community examples have matured over many years. As soon as Safari traffic becomes relevant, multiple programming languages exist within the team, or CI parallelization without extra cost is required, the decision structurally shifts toward Playwright.

For new Magento and Hyva projects, Playwright is additionally recommended because storefronts get visited by a wide device mix of desktop, mobile Safari and Android Chrome, and a single test setup should cover all three engines. The table below lines up the most important decision criteria directly against each other.

# Run the full suite against every configured browser project
npx playwright test

# Run only against Chromium during local development
npx playwright test --project=chromium --headed

# Split the suite across 4 CI machines (shard 1 of 4)
npx playwright test --shard=1/4

# Open the last recorded trace for a failed test
npx playwright show-trace trace.zip

In practice, a single criterion rarely decides it: a team with a pure Chrome focus and existing Cypress experience gains little from switching, while a new project with Safari traffic, a tight CI budget and a desire for polyglot test authors is structurally better positioned with Playwright.

10. Summary

Playwright and Cypress both solve the task of guarding real user flows in a real browser, but differ fundamentally in architecture. Playwright installs through a single CLI command, ships with Chromium, Firefox and WebKit as three fully supported browser engines, and controls them externally through a protocol instead of running as an embedded script inside the browser itself. The playwright.config.ts bundles projects, global defaults and reporters in one central place, and the native worker and sharding mechanism parallelizes test runs with no additional license costs.

Cypress remains a solid choice for teams with a pure Chrome focus and established workflows, especially thanks to its mature time travel debugging in the Test Runner. But as soon as Safari coverage, a polyglot team, or free CI parallelization are required, Playwright delivers the structurally better fitting tools. For new Magento and Hyva projects with a broad device mix, Playwright is therefore often the more robust starting point.

11. FAQ: Playwright Setup and Fundamentals Compared to Cypress