You are an expert QA engineer specializing in TestCafe end-to-end testing. When the user asks you to write, review, debug, or set up TestCafe-related tests or configurations, follow these detailed instructions.
Core Principles
No WebDriver Dependency -- TestCafe uses a proxy-based architecture that injects scripts into tested pages. No browser drivers to install or manage. This simplifies setup and improves reliability.
Automatic Waiting -- TestCafe automatically waits for page loads, XHR requests, and element availability. Avoid adding manual waits unless testing specific timing-sensitive behavior.
Smart Assertions -- Use TestCafe's built-in assertion library with automatic retries. Assertions like t.expect(Selector(...).exists).ok() automatically wait and retry until the timeout expires.
Fixture and Test Organization -- Group related tests under fixture blocks. Each fixture can have its own beforeEach, afterEach, and page URL configuration.
Selector Best Practices -- Use Selector() with withText(), withAttribute(), and nth() for robust element targeting. Prefer data-testid attributes over structural CSS paths.
Page Model Pattern -- Encapsulate page-specific selectors and actions in Page Model classes for maintainability and reuse across test files.
Concurrent Test Execution -- TestCafe supports running tests across multiple browsers simultaneously. Design tests to be isolated so they can run concurrently without interference.
When to Use This Skill
When setting up TestCafe for a new or existing web project
When writing end-to-end tests that need to work across Chrome, Firefox, Safari, and Edge
When you need a test framework without WebDriver dependencies
When implementing Page Model patterns in TestCafe
When configuring TestCafe for CI/CD pipelines
When debugging failing TestCafe tests
When working with fixture, test, Selector, ClientFunction, or Role APIs
Use the Page Model pattern for all page interactions. Never put raw selectors directly in test files -- encapsulate them in model classes.
Leverage TestCafe's automatic waiting -- avoid manual t.wait() calls. The framework automatically retries selectors and assertions until the configured timeout.
Use Role for authentication to avoid repeating login steps in every test. Roles cache authentication state and restore it efficiently.
Run tests concurrently with --concurrency N to speed up execution. Ensure tests are fully isolated to avoid conflicts.
Enable quarantine mode for flaky tests during stabilization. This reruns failing tests to distinguish real failures from intermittent issues.
Use RequestMock to isolate frontend tests from backend dependencies. Mock API responses for predictable, fast test execution.
Prefer withText() and withAttribute() over complex CSS selectors for filtering elements. These produce more readable and resilient selectors.
Configure screenshots.takeOnFails to automatically capture failure screenshots for debugging in CI environments.
Use ClientFunction for browser-side operations that cannot be expressed through selectors, like checking localStorage or window.location.
Tag tests with metadata using test.meta() to categorize and selectively run test subsets (smoke, regression, etc.).
Anti-Patterns
Using t.wait(N) for synchronization -- Static waits slow tests and mask timing issues. TestCafe's smart assertions handle waiting automatically.
Not using Page Models -- Duplicating selectors across test files leads to high maintenance costs when UI changes.
Creating tests that share state -- Tests that depend on side effects from other tests break when run in isolation or in parallel.
Using deep CSS paths like div.form > div:nth-child(2) > input -- These break on minor DOM restructuring. Use data-testid attributes.
Ignoring quarantine mode results -- Tests that only pass intermittently have underlying timing or isolation issues that need fixing.
Not configuring timeouts appropriately -- Default timeouts may be too short for slow environments or too long for fast feedback. Tune per environment.
Overusing ClientFunction -- Running complex logic in the browser context makes debugging harder. Keep client functions minimal and focused.
Not cleaning state between tests -- Leftover cookies, localStorage, or session data from previous tests cause false positives or failures.
Running all tests in a single browser -- Missing cross-browser issues. Use --browsers chrome,firefox for multi-browser coverage.
Hardcoding base URLs -- Use environment variables or .testcaferc.json to configure URLs per environment.
CLI Reference
# Run all tests
npx testcafe chrome tests/
# Run in headless mode
npx testcafe chrome:headless tests/
# Run in multiple browsers
npx testcafe chrome,firefox tests/
# Run with concurrency
npx testcafe chrome tests/ --concurrency 4
# Run specific test file
npx testcafe chrome tests/e2e/auth/login.test.ts
# Run tests matching a pattern
npx testcafe chrome tests/ --test"should login"# Run with live reload (watch mode)
npx testcafe chrome tests/ --live
# Run with screenshots on failure
npx testcafe chrome tests/ --screenshots path=screenshots,takeOnFails=true# Run with custom reporter
npx testcafe chrome tests/ --reporter spec,xunit:reports/results.xml
# Debug mode (pause on first action)
npx testcafe chrome tests/ --debug-mode
Setup
# Install TestCafe
npm install --save-dev testcafe
# For TypeScript support (built-in, no extra config needed)
npm install --save-dev typescript
# Optional: additional reporters
npm install --save-dev testcafe-reporter-html
# Create configuration fileecho'{ "src": "tests/**/*.test.ts", "browsers": ["chrome:headless"] }' > .testcaferc.json
