testzeus-test-suites

Create and manage test suites with workflow orchestration in TestZeus.

Category: execution · Version: 1.0.0 · Requires: testzeus-auth

Triggers: test suite, create suite, workflow, suite run, orchestrate tests, schedule suite, suite workflow, DAG, node, edge, workflow definition, suite orchestration

Overview

Test suites in TestZeus allow you to orchestrate multiple tests into a directed acyclic graph (DAG) workflow. Tests can run sequentially or in parallel, with dependencies between nodes.

Quick Reference

# List suites
testzeus test-suites list

# Get suite details
testzeus test-suites get suite_id

# Create suite
testzeus test-suites create \
  --name "checkout-flow" \
  --workflow-definition '{...}'

# Run suite
testzeus test-suite-runs create \
  --name "Run" \
  --test-suite suite_id \
  --input-values '{"base_url": "https://staging.example.com"}'

# Control runs
testzeus test-suite-runs pause run_id --mode graceful
testzeus test-suite-runs resume run_id
testzeus test-suite-runs cancel run_id

Workflow Definition Structure

The workflow definition defines the DAG structure of your test suite:

{
  "version": "1.0",
  "inputs": [
    {"name": "base_url", "type": "string", "required": true},
    {"name": "locale", "type": "string", "required": false, "default": "en-US"}
  ],
  "nodes": [
    {
      "id": "login",
      "name": "Login Flow",
      "test_id": "test_login_id",
      "inputs": {"base_url": "$base_url"},
      "settings": {"timeout": 300, "retries": 2}
    },
    {
      "id": "checkout",
      "name": "Checkout Flow",
      "test_id": "test_checkout_id",
      "inputs": {"base_url": "$base_url", "locale": "$locale"}
    }
  ],
  "edges": [
    {
      "id": "login-to-checkout",
      "from_node": "login",
      "to_node": "checkout",
      "dependency_type": "temporal"
    }
  ],
  "outputs": [],
  "settings": {"max_parallel_nodes": 3}
}

Workflow Components

Version

• version: Must be “1.0”

Inputs (Optional)

Define suite-level input parameters:

"inputs": [
  {"name": "base_url", "type": "string", "required": true},
  {"name": "count", "type": "number", "required": false, "default": 10}
]

Nodes

Each node represents a test or nested suite:

"nodes": [
  {
    "id": "unique_node_id",
    "name": "Human-readable name",
    "test_id": "actual_test_uuid",
    "suite_id": "nested_suite_uuid",  // OR this (not both)
    "inputs": {"param": "value"},
    "settings": {
      "timeout": 300,
      "retries": 2,
      "continue_on_failure": false
    }
  }
]

Edges

Define dependencies between nodes:

"edges": [
  {
    "id": "edge_id",
    "from_node": "node_id_1",
    "to_node": "node_id_2",
    "dependency_type": "temporal"  // or "hard"
  }
]

Dependency Types:

• temporal: Wait for completion, run regardless of result

• hard: Stop if upstream fails

Settings

"settings": {
  "max_parallel_nodes": 5,
  "failure_strategy": "stop"  // or "continue"
}

Create Test Suite

Basic Sequential Flow

testzeus test-suites create \
  --name "Checkout Flow" \
  --execution-mode lenient \
  --workflow-definition '{
    "version": "1.0",
    "nodes": [
      {
        "id": "login",
        "name": "Login",
        "test_id": "y9b88f17vabx476"
      },
      {
        "id": "add_cart",
        "name": "Add to Cart",
        "test_id": "x8c77f26uabx585"
      },
      {
        "id": "checkout",
        "name": "Checkout",
        "test_id": "w7d66e15tabx694"
      }
    ],
    "edges": [
      {"id": "e1", "from_node": "login", "to_node": "add_cart", "dependency_type": "temporal"},
      {"id": "e2", "from_node": "add_cart", "to_node": "checkout", "dependency_type": "temporal"}
    ]
  }'

With Input Schema

testzeus test-suites create \
  --name "Parameterized Suite" \
  --input-schema '[{"name": "base_url", "type": "string", "required": true}, {"name": "locale", "type": "string", "required": false}]' \
  --default-inputs '{"locale": "en-US"}' \
  --workflow-definition '{...}'

With Tags and Notifications

testzeus test-suites create \
  --name "Critical Path" \
  --tags regression \
  --notification-channels channel_id_1 \
  --workflow-definition '{...}'

Manage Test Suites

List Suites

testzeus test-suites list
testzeus test-suites list --filters status=ready

Get Suite Details

testzeus test-suites get suite_id
testzeus test-suites get suite_id --expand tests,environment

Update Suite

# Update name and status
testzeus test-suites update suite_id \
  --name "New Name" \
  --status ready

# Update workflow
testzeus test-suites update suite_id \
  --workflow-definition '{...}'

Delete Suite

testzeus test-suites delete suite_id

Run Test Suites

Create Run

testzeus test-suite-runs create \
  --name "Checkout Daily Run" \
  --test-suite suite_id \
  --input-values '{"base_url": "https://staging.example.com"}'

Control Runs

# Pause (graceful)
testzeus test-suite-runs pause run_id --mode graceful --reason "Maintenance window"

# Pause (force)
testzeus test-suite-runs pause run_id --mode force

# Resume
testzeus test-suite-runs resume run_id

# Cancel
testzeus test-suite-runs cancel run_id

# Delete
testzeus test-suite-runs delete run_id

List Runs

testzeus test-suite-runs list
testzeus test-suite-runs list --filters status=running

Get Run Details

testzeus test-suite-runs get run_id

View Node Runs

testzeus test-suite-node-runs list \
  --filters test_suite_run=run_id

testzeus test-suite-node-runs get node_run_id

Schedule Suite Runs

# Create schedule
testzeus test-suite-schedules create \
  --name "Daily Checkout" \
  --test-suite suite_id \
  --cron-expression "0 9 * * *" \
  --input-values '{"base_url": "https://staging.example.com"}' \
  --notification-channels channel_id

# List schedules
testzeus test-suite-schedules list

# Update schedule
testzeus test-suite-schedules update schedule_id \
  --cron-expression "0 10 * * *" \
  --is-active true

# Delete schedule
testzeus test-suite-schedules delete schedule_id

Nested Suites

Create hierarchical test execution:

testzeus test-suites create \
  --name "E2E Suite" \
  --workflow-definition '{
    "version": "1.0",
    "nodes": [
      {
        "id": "auth",
        "name": "Auth Suite",
        "suite_id": "auth_suite_id"
      },
      {
        "id": "main",
        "name": "Main Suite",
        "suite_id": "main_suite_id"
      }
    ],
    "edges": [
      {"id": "e1", "from_node": "auth", "to_node": "main", "dependency_type": "hard"}
    ]
  }'

Common Patterns

Parallel Execution

{
  "nodes": [
    {"id": "test1", "name": "Test 1", "test_id": "..."},
    {"id": "test2", "name": "Test 2", "test_id": "..."},
    {"id": "test3", "name": "Test 3", "test_id": "..."}
  ],
  "edges": [],
  "settings": {"max_parallel_nodes": 3}
}

Fan-In / Fan-Out

{
  "nodes": [
    {"id": "setup", "name": "Setup", "test_id": "..."},
    {"id": "test1", "name": "Test 1", "test_id": "..."},
    {"id": "test2", "name": "Test 2", "test_id": "..."},
    {"id": "teardown", "name": "Teardown", "test_id": "..."}
  ],
  "edges": [
    {"from_node": "setup", "to_node": "test1"},
    {"from_node": "setup", "to_node": "test2"},
    {"from_node": "test1", "to_node": "teardown"},
    {"from_node": "test2", "to_node": "teardown"}
  ]
}

SDK Usage

from testzeus_sdk import TestZeusClient

async def main():
    async with TestZeusClient() as client:
        # Create suite
        suite = await client.test_suites.create({
            "name": "checkout-flow",
            "execution_mode": "lenient",
            "workflow_definition": {
                "version": "1.0",
                "nodes": [
                    {"id": "login", "name": "Login", "test_id": "test_id"},
                    {"id": "checkout", "name": "Checkout", "test_id": "test_id_2"}
                ],
                "edges": [
                    {"from_node": "login", "to_node": "checkout", "dependency_type": "temporal"}
                ]
            }
        })
        
        # Run suite
        run = await client.test_suite_runs.run(
            display_name="Daily Checkout",
            test_suite=suite.id,
            input_values={"base_url": "https://staging.example.com"}
        )
        
        # Control
        await client.test_suite_runs.pause(run.id, mode="graceful")
        await client.test_suite_runs.resume(run.id)

Error Handling

Common Errors

Error	Cause	Solution
Invalid workflow	Malformed JSON	Validate JSON syntax
Node not found	Missing test_id	Ensure test exists
Cycle detected	Circular dependencies	Remove circular edges
Suite not ready	Status not “ready”	Update status first

Debugging

# Get expanded run details
testzeus test-suite-runs get run_id --expand nodes

# List node run details
testzeus test-suite-node-runs list --filters test_suite_run=run_id

Component Schema

Use TestSuiteView component:

{
  "component": "TestSuiteView",
  "props": {
    "suiteName": "checkout-flow",
    "nodes": [
      {"id": "login", "name": "Login", "status": "passed", "duration": "1.2s"},
      {"id": "cart", "name": "Cart", "status": "failed", "duration": "0.8s"},
      {"id": "checkout", "name": "Checkout", "status": "skipped", "duration": "0s"}
    ],
    "executionMode": "lenient"
  }
}

Use SuiteRunCard component:

{
  "component": "SuiteRunCard",
  "props": {
    "name": "checkout-flow",
    "runId": "run_123",
    "status": "running",
    "progress": {"completed": 2, "total": 5},
    "duration": "3m 45s"
  }
}

Related Skills

• testzeus-test-operations - Running individual tests

• testzeus-scheduling - Schedule suite runs

• testzeus-notifications - Configure alerts