# Cypress Website Test Runner (`produkdigitalali/cypress-website-test-runner`) Actor

Run automated website smoke tests in the cloud with Cypress. Check page loads, selectors, text, titles, URLs, visibility, and save screenshots for every result.

- **URL**: https://apify.com/produkdigitalali/cypress-website-test-runner.md
- **Developed by:** [ProdukDigitalAli](https://apify.com/produkdigitalali) (community)
- **Categories:** Developer tools, Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What is Cypress Website Test Runner?

Cypress Website Test Runner runs safe, declarative website smoke checks with Cypress in the Apify cloud.

Give it a public website URL and a list of checks. The Actor launches Cypress, executes the checks, and returns structured pass/fail results that can be consumed from the Apify Console, REST API, schedules, webhooks, and automation workflows.

It is designed for uptime-style smoke testing, QA monitoring, deployment verification, and simple browser checks without requiring users to maintain their own Cypress infrastructure.

> This Actor uses the open-source Cypress test runner. It is an independent tool and is not affiliated with or endorsed by Cypress.io. It does not record runs to the Cypress Cloud service.

### Supported checks

The MVP supports these declarative check types:

- `pageLoads` — verifies the target responds with an HTTP status below 400
- `selectorExists` — verifies a CSS selector exists
- `selectorVisible` — verifies a CSS selector is visible
- `textContains` — verifies visible page text exists
- `titleContains` — verifies the page title contains a value
- `urlContains` — verifies the final browser URL contains a value
- `selectorTextContains` — verifies an element contains expected text

Private, local, and internal network targets are blocked.

### Example input

```json
{
  "targetUrl": "https://example.com",
  "testName": "Example.com smoke test",
  "browser": "chrome",
  "timeoutSeconds": 30,
  "screenshot": true,
  "video": false,
  "checks": [
    {
      "type": "pageLoads",
      "label": "Page responds successfully"
    },
    {
      "type": "selectorExists",
      "label": "Main heading exists",
      "selector": "h1"
    },
    {
      "type": "textContains",
      "label": "Expected text is visible",
      "text": "Example Domain"
    }
  ]
}
```

### Example output

Each check is stored as a separate Dataset item:

```json
{
  "targetUrl": "https://example.com",
  "testName": "Example.com smoke test",
  "checkIndex": 2,
  "checkType": "selectorExists",
  "label": "Main heading exists",
  "passed": true,
  "durationMs": 842,
  "error": null,
  "screenshotUrl": "https://api.apify.com/v2/key-value-stores/...",
  "videoUrl": null,
  "browser": "chrome",
  "browserVersion": "...",
  "cypressVersion": "15.20.1"
}
```

A machine-readable run summary is also written to the default Key-Value Store under the `SUMMARY` key.

### Common use cases

#### Deployment smoke tests

Run a few critical checks immediately after deploying a website.

#### Scheduled website QA

Use Apify Schedules to run tests hourly, daily, or weekly and connect the result to a webhook or downstream automation.

#### Landing-page monitoring

Verify that critical headlines, CTA buttons, forms, or other selectors still exist after content or CMS changes.

#### Multi-browser sanity checks

Run the same declarative checks using Chrome, Electron, Firefox, or Edge.

#### API-driven testing

Start the Actor from your own backend or workflow and consume the structured Dataset output programmatically.

### Input fields

#### Target URL

A public HTTP(S) website. Localhost, internal hostnames, and private IP ranges are rejected.

#### Checks

Provide between 1 and 50 checks.

Some check types require additional fields:

| Type | Required field |
| --- | --- |
| `pageLoads` | none |
| `selectorExists` | `selector` |
| `selectorVisible` | `selector` |
| `textContains` | `text` |
| `titleContains` | `value` |
| `urlContains` | `value` |
| `selectorTextContains` | `selector`, `text` |

#### Browser

Choose Chrome, Electron, Firefox, or Edge.

#### Screenshots and video

Screenshots are enabled by default. Video is disabled by default to keep compute usage lower.

### Automation

The Actor can be combined with:

- Apify Schedules
- REST API calls
- Webhooks
- Make
- Zapier
- CI/CD workflows
- Internal monitoring systems

### Security and responsible use

The Actor only accepts declarative checks. It does not execute arbitrary user-supplied JavaScript or Cypress spec code.

Targets resolving to localhost, private IP ranges, or common internal hostnames are rejected. Use the Actor only on websites you are authorized to test and in accordance with applicable terms and laws.

### Limitations

- This version is intended for lightweight smoke checks, not full application test suites.
- Authentication flows are not yet supported.
- Complex multi-step actions such as click/type/navigation sequences are not yet supported.
- A website may behave differently depending on region, bot protection, cookies, or browser fingerprinting.

### Roadmap

Possible future additions include:

- Multi-step click/type actions
- Login/session setup
- Request header and cookie configuration
- Network assertions
- Webhook-friendly failure summaries
- Visual comparison
- More detailed performance metrics

### Support

If a check behaves unexpectedly, open an issue on the Actor page and include:

- the public target URL
- the check configuration
- the expected result
- the actual result

Do not include passwords, API keys, session cookies, or other secrets in public issues.

# Actor input Schema

## `targetUrl` (type: `string`):

Public HTTP(S) URL to test.

## `testName` (type: `string`):

A human-readable name for this test run.

## `checks` (type: `array`):

Declarative checks to execute. Supported types: pageLoads, selectorExists, selectorVisible, textContains, titleContains, urlContains, selectorTextContains.

## `browser` (type: `string`):

Browser used by Cypress.

## `timeoutSeconds` (type: `integer`):

Timeout in seconds for page loads, requests, and Cypress commands.

## `viewportWidth` (type: `integer`):

Browser viewport width in pixels.

## `viewportHeight` (type: `integer`):

Browser viewport height in pixels.

## `retries` (type: `integer`):

Number of retries for failed checks.

## `screenshot` (type: `boolean`):

Capture a screenshot after successful checks. Cypress also captures failures automatically.

## `video` (type: `boolean`):

Record the Cypress run as a video. Disabled by default to reduce runtime cost.

## Actor input object example

```json
{
  "targetUrl": "https://example.com",
  "testName": "Example.com smoke test",
  "checks": [
    {
      "type": "pageLoads",
      "label": "Page responds successfully"
    },
    {
      "type": "textContains",
      "label": "Expected text is visible",
      "text": "Example Domain"
    }
  ],
  "browser": "chrome",
  "timeoutSeconds": 30,
  "viewportWidth": 1280,
  "viewportHeight": 720,
  "retries": 0,
  "screenshot": true,
  "video": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("produkdigitalali/cypress-website-test-runner").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("produkdigitalali/cypress-website-test-runner").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call produkdigitalali/cypress-website-test-runner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,produkdigitalali/cypress-website-test-runner"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/h7JrCCEji0N1P0sLF/builds/JJOGVzdKqAJwmQ8yg/openapi.json