Cloud Staging

Run any Apify actor in a sandboxed cloud environment, validate its output against structural checks and custom assertions, and get a PASS/FAIL test report. Cloud Staging Test is your CI/CD quality gate for Apify actors -- catch broken output schemas, missing fields, and data regressions before they reach production.

Cloud Staging Test executes a target actor with your test input, fetches its output dataset, runs structural validation (field consistency, type checking, schema compliance), evaluates custom assertions (minimum results, required fields, field types), and produces a single test report with a clear PASS or FAIL verdict. Use it in deployment pipelines, scheduled regression tests, or one-off quality checks.

What data can you extract?

Why use Cloud Staging Test?

Deploying an actor update without testing its output is like shipping code without running tests. An actor can succeed (status SUCCEEDED) while silently producing broken data -- missing fields, wrong types, fewer results than expected, or fields that don't match the dataset schema. These silent failures propagate through your pipelines before anyone notices.

Cloud Staging Test automates the validation step. Point it at any actor with a test input, define what "good output" looks like, and get a structured PASS/FAIL report. Integrate it into your deployment workflow so no broken actor reaches production.

Built on the Apify platform, Cloud Staging Test gives you capabilities you won't get from a simple script:

• Scheduling -- run nightly regression tests against all your actors
• API access -- trigger tests programmatically from CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)
• Monitoring -- get notified when tests fail via Apify webhooks
• Integrations -- connect to Zapier, Make, Slack, or any webhook endpoint for test failure alerts

Features

• Automatic structural validation that checks field consistency (are all items shaped the same?), type consistency (is a field always a string, or sometimes a number?), and empty array detection across all output items
• Dataset schema compliance that fetches the target actor's declared dataset schema and validates output against it -- catches undeclared fields and missing schema fields
• Custom assertions with three check types: minimum result count (minResults), required field presence (requiredFields), and field type validation (fieldTypes)
• Clear PASS/FAIL verdict based on run status, schema validation, and all assertion checks
• Configurable timeout and memory so you can match the target actor's normal run configuration
• Detailed error and warning reporting with specific messages for each validation issue
• Pay-per-event pricing at $0.50 per test run -- cheap enough for continuous testing

Use cases for cloud staging tests

CI/CD deployment gates

Run Cloud Staging Test as a post-deploy step in your actor CI/CD pipeline. If the test fails, roll back the deployment. This catches schema-breaking changes before they affect users.

Nightly regression testing

Schedule Cloud Staging Test to run every night against your critical actors. Detect output degradation from upstream website changes, API modifications, or platform updates.

Pre-release validation

Before publishing a new actor version to the Apify Store, run it through Cloud Staging Test with representative inputs to verify output quality meets your standards.

Actor evaluation

When evaluating third-party actors from the Apify Store, run them through Cloud Staging Test with your expected input to verify they produce the output structure and volume you need.

Data pipeline quality assurance

If your data pipeline depends on specific fields from an actor's output, define those as required fields in assertions. Catch missing fields before they break downstream processing.

Post-migration validation

After migrating from one actor to another, run both through Cloud Staging Test with the same input and compare the reports to verify the replacement produces equivalent output.

How to run a cloud staging test

1. Enter the target actor -- Provide the actor ID or username~name slug (e.g., ryanclinton/website-contact-scraper) you want to test.
2. Provide test input -- Enter a JSON object that will be passed to the target actor. Use a small, representative input that exercises the actor's core functionality.
3. Define assertions (optional) -- Set minimum result count, required output fields, and expected field types.
4. Configure runtime -- Set timeout and memory allocation to match the target actor's normal configuration.
5. Run the test -- Click "Start" and wait for the target actor to complete and validation to finish.
6. Review the report -- Check the PASS/FAIL verdict, schema validation details, and assertion results in the Dataset tab.

Input parameters

Input examples

Basic test with no assertions:

{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://example.com"],
        "maxPagesPerDomain": 3
    }
}

Test with full assertions:

{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://example.com"],
        "maxPagesPerDomain": 3
    },
    "assertions": {
        "minResults": 1,
        "requiredFields": ["url", "domain", "emails"],
        "fieldTypes": {
            "url": "string",
            "domain": "string",
            "emails": "array",
            "pagesScraped": "number"
        }
    },
    "timeout": 120,
    "memory": 512
}

Quick smoke test:

{
    "targetActorId": "ryanclinton/google-maps-email-extractor",
    "testInput": {
        "query": "plumbers in Chicago",
        "maxResults": 3,
        "scrapeWebsites": false
    },
    "assertions": {
        "minResults": 1,
        "requiredFields": ["businessName"]
    },
    "timeout": 60,
    "memory": 256
}

Input tips

• Use small test inputs -- limit URLs to 1-3 and result counts to 3-5. Tests should be fast and cheap, not comprehensive scrapers.
• Set assertions for critical fields -- at minimum, use requiredFields to verify your most important output fields exist.
• Match the actor's memory needs -- browser-based actors need 4096 MB, HTTP-only scrapers work with 256-512 MB.
• Set realistic timeouts -- allow enough time for the target actor to complete. 120 seconds is fine for simple scrapers, but complex actors may need 300+.

Output example

Each test run produces one report in the dataset:

{
    "targetActor": "ryanclinton/website-contact-scraper",
    "runId": "abc123def456",
    "runStatus": "SUCCEEDED",
    "runDuration": 8.3,
    "results": 1,
    "schemaValidation": {
        "passed": true,
        "errors": 0,
        "warnings": 2,
        "details": [
            "No dataset schema found — structural consistency checks only",
            "Field 'socialLinks' only present in 1/1 items (100%)"
        ]
    },
    "assertions": {
        "passed": true,
        "checks": [
            { "check": "minResults >= 1", "passed": true, "actual": 1 },
            { "check": "field 'url' exists", "passed": true },
            { "check": "field 'domain' exists", "passed": true },
            { "check": "field 'emails' exists", "passed": true },
            { "check": "field 'emails' is array", "passed": true, "actual": "array" }
        ]
    },
    "overallResult": "PASS",
    "testedAt": "2026-03-18T14:30:00.000Z"
}

Output fields

How much does it cost to run cloud staging tests?

Cloud Staging Test uses pay-per-event pricing -- you pay $0.50 per test run. This covers the orchestration and validation logic. The target actor run is billed separately at its own rate.

The Apify Free plan includes $5 of monthly credits -- enough for approximately 10 test runs (orchestration only, excluding target actor costs).

Tip: Use small test inputs (1-3 URLs, 3-5 results) to minimize target actor costs during testing.

Run cloud staging tests using the API

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("ryanclinton/cloud-staging-test").call(run_input={
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {
        "urls": ["https://example.com"],
        "maxPagesPerDomain": 3,
    },
    "assertions": {
        "minResults": 1,
        "requiredFields": ["url", "domain", "emails"],
        "fieldTypes": {"emails": "array", "pagesScraped": "number"},
    },
    "timeout": 120,
    "memory": 512,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"Result: {item['overallResult']}")
    print(f"Status: {item['runStatus']} | Duration: {item['runDuration']}s | Items: {item['results']}")
    print(f"Schema: {item['schemaValidation']['errors']} errors, {item['schemaValidation']['warnings']} warnings")
    for check in item["assertions"]["checks"]:
        status = "PASS" if check["passed"] else "FAIL"
        print(f"  [{status}] {check['check']}")

JavaScript

import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: "YOUR_API_TOKEN" });

const run = await client.actor("ryanclinton/cloud-staging-test").call({
    targetActorId: "ryanclinton/website-contact-scraper",
    testInput: {
        urls: ["https://example.com"],
        maxPagesPerDomain: 3,
    },
    assertions: {
        minResults: 1,
        requiredFields: ["url", "domain", "emails"],
        fieldTypes: { emails: "array", pagesScraped: "number" },
    },
    timeout: 120,
    memory: 512,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const report = items[0];

console.log(`Result: ${report.overallResult}`);
console.log(`Duration: ${report.runDuration}s | Items: ${report.results}`);
report.assertions.checks.forEach(c => {
    console.log(`  [${c.passed ? "PASS" : "FAIL"}] ${c.check}`);
});

cURL

# Start the test run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~cloud-staging-test/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetActorId": "ryanclinton/website-contact-scraper",
    "testInput": {"urls": ["https://example.com"], "maxPagesPerDomain": 3},
    "assertions": {"minResults": 1, "requiredFields": ["url", "domain", "emails"]},
    "timeout": 120,
    "memory": 512
  }'

# Fetch results (replace DATASET_ID from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"

How Cloud Staging Test works

The actor runs a four-phase pipeline:

Phase 1: Execute target actor

The actor calls Actor.call() with your target actor ID, test input, timeout, and memory settings. The target actor runs in a sandboxed Apify environment with its own dataset. If the call throws an error (timeout, crash, misconfiguration), the test immediately produces a FAIL report with the error message.

Phase 2: Fetch output data

After the target actor completes, Cloud Staging Test fetches all items from its output dataset using the Apify client. If the dataset fetch fails, the test continues with an empty item list and notes the failure.

Phase 3: Structural validation

Every output item is analyzed for structural quality:

• Field presence consistency -- checks if all items have the same top-level keys. Fields present in some items but not all generate warnings with the percentage present (e.g., "Field 'socialLinks' only present in 80% of items").
• Type consistency -- for each field, collects the JavaScript types across all items. Mixed types (e.g., a field that is sometimes a string and sometimes a number) generate warnings. Null mixed with one other type is allowed.
• Empty array detection -- fields containing empty arrays are flagged as warnings.
• Dataset schema compliance -- if the target actor has a declared dataset schema (from its latest build), output fields are validated against it. Extra fields not in the schema generate warnings. Schema fields missing from all output items generate errors.

Phase 4: Assertion evaluation

If custom assertions are provided, three types of checks run:

• minResults -- verifies the dataset contains at least N items. Fails if items.length < minResults.
• requiredFields -- for each field name, checks that at least one item has a non-null, non-undefined value for that field.
• fieldTypes -- for each field-type pair, verifies that all items with the field have the specified JavaScript type (string, number, boolean, object, or array).

The overall verdict is PASS only if the run succeeded, schema validation had zero errors, and all assertion checks passed.

Limitations

• One actor per test -- each run tests a single target actor. For testing multiple actors, run Cloud Staging Test multiple times or use the API to batch requests.
• No input validation -- the test input is passed directly to the target actor. If the input is invalid for the target actor's schema, the target run will fail, and the test will report FAIL.
• Schema validation is structural only -- checks field presence, types, and consistency. It does not validate data quality (e.g., whether email addresses are valid or phone numbers are real).
• No historical comparison -- each test run is independent. It does not compare results to previous runs. For output degradation detection, use Output Completeness Monitor.
• Dataset schema fetch is best-effort -- if the target actor's latest build doesn't have a dataset schema, structural validation runs without schema compliance checks.
• Target actor costs are separate -- the $0.50 test fee covers only the orchestration. The target actor run is billed at its own rate.

Integrations

• Zapier -- Trigger workflows when a test fails. Send alerts to Slack, create Jira tickets, or notify your team.
• Make -- Build automated test pipelines that run multiple actors through staging tests.
• Google Sheets -- Export test reports to Google Sheets for tracking test history.
• Apify API -- Integrate into CI/CD pipelines. Start test runs from GitHub Actions, GitLab CI, or any automation tool.
• Webhooks -- Receive notifications when tests complete. Route FAIL results to your alerting system.

Responsible use

• This actor executes other actors using your Apify API token. Only test actors you have permission to run.
• The target actor runs in your Apify account and consumes your compute credits.
• Respect target actor rate limits and terms of service, especially when testing third-party actors.
• Do not use this actor to stress-test or overload third-party actors.

FAQ

How does Cloud Staging Test differ from just running an actor manually? Running an actor manually tells you it completed. Cloud Staging Test tells you the output is structurally sound, matches the declared schema, and meets your specific quality criteria. It automates the inspection step.

Can I test actors I don't own? Yes. Any public actor on the Apify Store can be tested by providing its ID or username~name slug. The run executes under your account and credits.

What if the target actor takes longer than the timeout? The test reports FAIL with status TIMED-OUT. Increase the timeout parameter to accommodate slower actors.

Can I use this in GitHub Actions? Yes. Use the Apify API to trigger a test run, poll for completion, and check the overallResult field. Exit with a non-zero code if the result is FAIL. See the Python and cURL API examples above.

What counts as a schema validation error vs. warning? Errors are hard failures: a field defined in the dataset schema is completely missing from all output items. Warnings are soft issues: inconsistent field presence across items, mixed types, empty arrays, or extra fields not in the schema.

Can I test with multiple different inputs? Not in a single run. Each run takes one test input. For multiple input scenarios, run separate tests and compare the reports.

How do I define field type assertions? Use JavaScript type names: "string", "number", "boolean", "object", "array". For example, "fieldTypes": {"emails": "array", "pagesScraped": "number"} checks that the emails field is always an array and pagesScraped is always a number.

What happens if the target actor produces zero results? Schema validation passes with a warning ("No items to validate"). If you have a minResults assertion, it will fail. The overall result depends on whether assertions are defined.

Related actors

Support

Found a bug or have a feature request? Open an issue in the Issues tab on this actor's page. For custom solutions or enterprise integrations, reach out through the Apify platform.