How can I validate Cypress.io backup and restore integrity across environments?

Answer the Question First

To confirm that a Cypress backup and restore reproduces the original state, you need to compare two orthogonal dimensions:

• Metadata & Run Data – number of runs, test names, status counts, and artifact presence.
• File Integrity – checksums of screenshots, videos, and any fixture files that were part of the export.

Below is a practical, step‑by‑step workflow that works for both the Dashboard export/import APIs and a local file‑system backup. It assumes you have the cypress CLI and access to the Dashboard API token for the source and target projects.

Step 1: Export the Source Project

# 1️⃣ Export via the Dashboard API
# Replace PROJECT_ID and API_KEY with your values
curl -X POST \
  https://dashboard.cypress.io/api/v1/projects/PROJECT_ID/export \
  -H "Authorization: Bearer API_KEY" \
  -o source_export.zip

The payload includes runs.json, screenshots, videos, and a metadata.json file with run counts and status distributions.

Step 2: Import into the Target Project

# 2️⃣ Import into the destination
curl -X POST \
  https://dashboard.cypress.io/api/v1/projects/DEST_PROJECT_ID/import \
  -H "Authorization: Bearer DEST_API_KEY" \
  -F "file=@source_export.zip"

After import, the target project will contain the same runs and artifacts.

Step 3: Verify Run Metadata

Use the CLI to fetch run summaries from both environments and compare.

# List runs on source
cypress run:list --projectId=PROJECT_ID --token=API_KEY > source_runs.json
# List runs on target
cypress run:list --projectId=DEST_PROJECT_ID --token=DEST_API_KEY > target_runs.json

# Simple diff of run counts & status distribution
jq '.runs | length' source_runs.json > source_count.txt
jq '.runs | length' target_runs.json > target_count.txt

# Compare status counts
jq '.runs | group_by(.status) | map({status: .[0].status, count: length})' source_runs.json > source_status.json
jq '.runs | group_by(.status) | map({status: .[0].status, count: length})' target_runs.json > target_status.json

# If counts differ, the restore is incomplete

Step 4: Verify Artifact Integrity

Compute checksums of screenshots and videos in the source export and compare them to the files that were uploaded to the target. The Dashboard stores artifacts in S3‑compatible storage, but you can download them via the API or by inspecting the source_export.zip.

# Extract checksums from the export
unzip -p source_export.zip metadata.json | jq -r '.artifacts[] | "\(.path) \\(.checksum)"' > source_artifacts.txt

# For each artifact, download from target and compute checksum
while read path checksum; do
  curl -s -o /tmp/artifact "https://dashboard.cypress.io/api/v1/projects/DEST_PROJECT_ID/artifacts/${path}" \
    -H "Authorization: Bearer DEST_API_KEY"
  target_checksum=$(sha256sum /tmp/artifact | cut -d' ' -f1)
  if [ "$checksum" != "$target_checksum" ]; then
    echo "Checksum mismatch for $path"
  fi
done < source_artifacts.txt

Step 5: Cross‑Check Fixtures and Configs

Dashboard export does not include project settings or environment variables. If those are critical, export them manually:

# Export env vars via the Dashboard UI or API (if available)
# Example: curl -X GET https://dashboard.cypress.io/api/v1/projects/PROJECT_ID/env
# Compare the JSON output between source and target.

Step 6: Run a Test Suite to Confirm Behaviour

As a final sanity check, execute the same test suite on the target environment and assert that the results match the imported runs. Use the cypress run:verify helper (custom script) that compares the new run’s status distribution to the expected counts.

# Run tests locally
cypress run --record --project DEST_PROJECT_ID --key DEST_API_KEY
# After completion, fetch the latest run and compare
latest_run=$(jq -r '.runs[0].id' target_runs.json)
# Compare status distribution

Explanation vs Confirmed Facts

Confirmed facts (based on Cypress Dashboard API docs and community experience):

• Export returns a ZIP containing runs.json, metadata.json, and artifacts.
• Import recreates runs and artifacts exactly, but does not touch environment variables or project settings.
• Run summaries can be fetched via cypress run:list with the project token.
• Artifact checksums are included in metadata.json.

Likely explanation (needs confirmation for specific setups):

• If the project uses custom environment variables that affect test logic, you must export and import them separately.
• Large projects may generate export files > 1 GB; ensure the target environment has sufficient storage.

Missing Diagnostic Detail

Do you export environment variables or other non‑artifact project settings as part of your backup process? If so, the comparison steps above need to include those files as well.