Modern Web Testing with TestCafe

TestCafe is a Node.js-based framework for end-to-end testing web applications. Write tests in JavaScript or TypeScript, then run them from the command line against a selected browser. It tests the application through its browser-facing interface, so the application backend can use a different language or framework. The open-source runner is a fit for code-authored tests; TestCafe Studio is a separate commercial desktop option with visual recording and codeless workflows. TestCafe project · Official documentation.

What TestCafe does

An end-to-end test drives a browser through a user flow and checks the resulting page state. A test might open a sign-in page, enter credentials, submit a form, and assert that a dashboard heading appears. TestCafe supplies the test runner and browser actions; your application can be written in Ruby, Node.js, Rust, C#, PHP, or another stack.

TestCafe documents automatic waiting around navigation, actions, selectors, and assertions, plus concurrent execution, JavaScript error detection, live mode, and CI integration. These are mechanisms to help structure runs; they do not guarantee that every test is stable or faster. Use stable selectors, isolate test data, and make asynchronous states explicit.

Install TestCafe and create a first test

1. Check the prerequisites

Install Node.js and npm, then use a supported operating system: Linux, Windows, or macOS. Install or configure a browser that you plan to run locally, or set up an appropriate remote browser provider. Check the current setup documentation and browser requirements before pinning versions in a project.

2. Add TestCafe to the project

mkdir testcafe-demo
cd testcafe-demo
npm init -y
npm install --save-dev testcafe

A local development dependency keeps the runner version recorded in the project lockfile and lets teammates and CI use the same installed version. The official getting-started page also documents global installation; for project work, a local dependency makes the intended version easier to reproduce.

3. Write a representative test

Create tests/example.js with this small test against TestCafe’s public example page:

import { Selector } from 'testcafe';

fixture('Example page')
  .page('https://devexpress.github.io/testcafe/example/');

test('updates the developer name', async t => {
  const nameInput = Selector('#developer-name');
  const submitButton = Selector('#submit-button');
  const header = Selector('#article-header');

  await t
    .typeText(nameInput, 'Ada Lovelace')
    .click(submitButton)
    .expect(header.innerText).eql('Thank you, Ada Lovelace!');
});

The fixture groups tests and supplies the starting page. The test uses selectors to locate controls, awaits browser actions, and checks the resulting text. For your own app, replace the URL, selectors, and expected result with stable parts of your product. Prefer dedicated test attributes such as data-testid when the UI structure changes frequently.

4. Run the test

npx testcafe chrome tests/example.js

The general command shape is testcafe <browser> <test-file-or-glob>. For example, after installing Firefox you can run npx testcafe firefox tests/. The browser alias must resolve to an available browser or configured remote environment. The shell report shows the outcome and failure details.

To make the command convenient, add a package script:

{
  "scripts": {
    "test:e2e": "testcafe chrome tests/"
  }
}

npm run test:e2e

Choose selectors and assertions that survive UI changes

TestCafe selectors identify elements in the page. A selector can target an ID, CSS class, attribute, or other supported element property. Use selectors that express user-facing intent where possible, and avoid depending on generated class names or incidental DOM nesting. When a target appears asynchronously, TestCafe’s selector and assertion waiting can allow it time to appear; still assert a meaningful end state rather than inserting arbitrary delays everywhere.

Stable target: Prefer an ID or a dedicated test attribute that the team treats as part of the testing interface.
Unique target: Check that a selector matches the intended single control; ambiguous selectors can cause actions to hit the wrong element.
Visible and enabled state: Assert that controls are ready before interacting when the application has loading or disabled states.
Independent tests: Reset or create test data so one test’s outcome does not depend on the order of earlier tests.
Useful failure context: Give tests names that identify the user flow and keep assertion messages or reporters informative.

Run across browsers and execution environments

The browser guide lists Chromium, Chrome, Chrome Canary, Chromium-based Edge, Firefox, Opera, and Safari, along with remote, cloud, mobile, headless, and emulation options. Availability depends on the actual environment and configuration; distinguish a browser installed on the local machine from one provided remotely. TestCafe 3.0 discontinued official support for Internet Explorer 11 and legacy Microsoft Edge.

The FAQ says the project guarantees compatibility with the two latest versions of each popular browser, subject to documented exceptions. That statement and the browser list can change. Confirm exact browser versions, operating systems, and modes against the current browser guide before deciding that a particular production configuration is covered.

Run more than one browser

You can specify more than one browser in a run where the environment supports them. Verify each browser can be launched and connected before relying on the command in CI. For teams with different browser requirements, split runs by browser family so logs and failures remain clear.

For mobile device coverage or cloud browsers, follow the provider’s current TestCafe integration instructions. The project README discusses provider plugins and BrowserStack infrastructure; the documentation also describes remote browser workflows. Check current provider support, credentials handling, and commercial terms rather than assuming a past integration is still available.

Run TestCafe in CI

CI runs use the same project dependency and test files as local runs, but need a browser environment and a command that exits with the test result. A minimal pipeline step after dependency installation is:

npm ci
npx testcafe chrome tests/

The CI image or runner must have a compatible browser available, or use the documented remote/cloud configuration. Store credentials in the CI system’s secret store if your application or provider requires them; do not commit secrets into test files. Keep browser versions and dependency installation reproducible, and save test output or reports using the CI system’s artifact mechanism when useful.

TestCafe supports concurrent test execution and CI integration. Concurrency is an execution choice, not a free reliability improvement: tests that share accounts, records, or mutable state may interfere with each other. Begin with isolated tests and increase concurrency only when shared resources are safe. Review the current concurrent execution guide and reporting options for your workflow.

Open-source runner or TestCafe Studio?

Choice	Useful when	Consider
TestCafe runner	The team authors and reviews tests as JavaScript or TypeScript code and wants command-line and CI workflows.	Requires basic JavaScript and Node.js familiarity. The framework is available under the MIT license.
TestCafe Studio	The team wants an interactive desktop workflow, visual recording, or codeless test authoring.	It is a separate commercial product. Check current license terms and the limits of codeless tests.

The official FAQ says both options can run the same tests and describes the difference primarily as workflow. Studio can record JavaScript and TypeScript tests and supports codeless tests, which do not expose the full range of TestCafe capabilities. See the official FAQ for current licensing and product details.

Configuration and practical operating choices

Start with the CLI options and configuration your team actually needs; confirm option names and defaults in the current documentation because they can change. The configuration file can select browsers and other run settings. The official configuration guide notes that configuration files do not support ESM syntax; use CommonJS, and use a .cjs extension when the surrounding project is configured as an ES module.

Browser selection: Choose local aliases, custom executable paths, or a documented remote/cloud setup.
Concurrency: Increase workers only after tests and data are independent; observe resource use and failure output.
Timeouts and waiting: Prefer condition-based selectors and assertions. Adjust timeouts only when a known environment requires it, and keep them consistent with real page behavior.
Reporting: Choose output that CI can retain and developers can diagnose. Verify reporter availability and format in current docs.
Versioning: Commit the package lockfile and use a deterministic install in CI. Recheck the release page when upgrading.

Performance, reliability, and cost

Runtime depends on page load behavior, browser startup, the number of tests and browsers, remote infrastructure, and configured concurrency. No single speed figure applies to every application. Measure the suite in the same environment used for CI, identify slow flows, and use concurrency only where isolation permits it.

Automatic waiting can avoid some timing mistakes by waiting for relevant page conditions, but it cannot make unstable application state deterministic. Reduce flakiness by using stable selectors, waiting on meaningful state, cleaning up test data, and avoiding tests that depend on execution order. For failures, retain enough report output to distinguish a browser startup issue from an application assertion failure.

The TestCafe runner is open source under the MIT license. TestCafe Studio is separately purchasable from DevExpress. Remote or cloud browser services may have their own costs and terms; verify them with the provider. Browser compatibility, integrations, release status, and licensing details are time-sensitive. The official release page currently surfaces v3.7.6, but check the release listing before selecting a version for a new project.

Troubleshooting common failures

Symptom	Likely cause	What to check or fix
Command not found	TestCafe is installed locally but invoked as a global command.	Run it with `npx testcafe` or through an npm script after installing the project dependency.
Browser fails to start or connect	The alias is unavailable, the executable path is wrong, or a remote browser is not configured.	Confirm the browser is installed and launchable in that environment; recheck custom paths, provider setup, and initialization settings.
Selector or assertion times out	The element is absent, the selector is stale or ambiguous, or the expected state never occurs.	Inspect the rendered page and selector match. Use a stable attribute and assert the actual end state. Check whether the application is waiting on an API or authentication flow.
Action targets the wrong element	The selector matches multiple elements or relies on unstable structure.	Narrow the selector and assert uniqueness or the intended element’s properties before acting.
Tests pass locally but fail in CI	Different browser versions, environment variables, network access, data state, or timing.	Align dependency/browser setup, provide required secrets and services, isolate test data, and inspect CI’s browser and page output.
Parallel run is inconsistent	Tests share accounts or mutate the same data.	Give workers isolated data or accounts, or reduce concurrency until test state is independent.
Configuration file fails to load	ES module syntax is used in a config file that expects CommonJS.	Use `require`; if the package uses `type: module`, use the documented `.cjs` extension.

Or skip the browser setup

TestCafe is for interactive end-to-end flows. If the task is to capture a page as an image or PDF, ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request returns PNG, JPEG, WebP, or PDF. 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);

Cookie banners are accepted and removed before capture; known newsletter popups and chat widgets are removed too. Each cleanup step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Response headers report the page verdict and billing status.
An MCP server exposes take_screenshot, get_page_info, and capture_pdf to AI agents and MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan.

Adoption checklist

Confirm the required browser families, versions, and operating systems against the current browser guide.
Run a representative end-to-end flow in the same environment you expect to use in CI.
Use stable selectors and isolate test data before enabling concurrency.
Decide whether code-authored tests fit the team, or whether Studio’s visual and codeless workflow justifies its separate license.
Review the current release, browser support, provider integrations, and commercial terms before rollout.

FAQ

Does the application need to use Node.js?

No. Node.js runs the TestCafe tooling. The web application backend can use another language; tests exercise the app through the browser.

Can I write TestCafe tests in TypeScript?

Yes. JavaScript and TypeScript are documented authoring languages. CoffeeScript is also listed in the official FAQ.

Does TestCafe guarantee tests will not be flaky?

No. Automatic waiting helps with some asynchronous page conditions, but selectors, shared state, network behavior, and application timing still need deliberate test design.

Is TestCafe Studio required to run TestCafe tests?

No. The open-source command-line runner can author and run code-based tests. Studio is an optional commercial workflow with recording and codeless authoring features.