Create Block Test - Retab Docs

from retab import Retab

client = Retab()

# Manual inputs: hand-write the handle inputs the block should run with.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "manual",
        "handle_inputs": {
            "input-document-0": {
                "type": "file",
                "file_id": "file_invoice_q1",
            },
        },
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "total"},
        "condition": {"kind": "equals", "expected": 1234.56},
    },
    name="Q1 invoice total",
)

# Run-step inputs: replay the inputs the block ACTUALLY received in a run.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "run_step",
        "run_id": "wfrun_def456",
        "step_id": "block_extract_invoice",
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "vendor.name"},
        "condition": {"kind": "contains", "expected": "Acme"},
    },
)

print(f"Test created: {test.id}")

{
  "id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "workflow_id": "wf_abc123xyz",
  "organization_id": "org_123",
  "target": {
    "type": "block",
    "block_id": "block_extract_invoice"
  },
  "source": {
    "type": "manual",
    "handle_inputs": {
      "input-document-0": {
        "type": "file",
        "file_id": "file_invoice_q1"
      }
    }
  },
  "name": "Q1 invoice total",
  "assertion": {
    "id": "assert_xyz",
    "target": { "output_handle_id": "output-json-0", "path": "total" },
    "condition": { "kind": "equals", "expected": 1234.56 },
    "label": null
  },
  "assertion_schema_dep": {
    "schema_path": "total",
    "subtree_hash": "7d79dd764ab6548d",
    "depends_on_root": false
  },
  "assertion_drift_status": null,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "validation_status": "valid",
  "validation_issues": [],
  "latest_run_summary": null,
  "latest_passing_run_summary": null,
  "latest_failing_run_summary": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

POST

workflows

{workflow_id}

block-tests

from retab import Retab

client = Retab()

# Manual inputs: hand-write the handle inputs the block should run with.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "manual",
        "handle_inputs": {
            "input-document-0": {
                "type": "file",
                "file_id": "file_invoice_q1",
            },
        },
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "total"},
        "condition": {"kind": "equals", "expected": 1234.56},
    },
    name="Q1 invoice total",
)

# Run-step inputs: replay the inputs the block ACTUALLY received in a run.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "run_step",
        "run_id": "wfrun_def456",
        "step_id": "block_extract_invoice",
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "vendor.name"},
        "condition": {"kind": "contains", "expected": "Acme"},
    },
)

print(f"Test created: {test.id}")

{
  "id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "workflow_id": "wf_abc123xyz",
  "organization_id": "org_123",
  "target": {
    "type": "block",
    "block_id": "block_extract_invoice"
  },
  "source": {
    "type": "manual",
    "handle_inputs": {
      "input-document-0": {
        "type": "file",
        "file_id": "file_invoice_q1"
      }
    }
  },
  "name": "Q1 invoice total",
  "assertion": {
    "id": "assert_xyz",
    "target": { "output_handle_id": "output-json-0", "path": "total" },
    "condition": { "kind": "equals", "expected": 1234.56 },
    "label": null
  },
  "assertion_schema_dep": {
    "schema_path": "total",
    "subtree_hash": "7d79dd764ab6548d",
    "depends_on_root": false
  },
  "assertion_drift_status": null,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "validation_status": "valid",
  "validation_issues": [],
  "latest_run_summary": null,
  "latest_passing_run_summary": null,
  "latest_failing_run_summary": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Create a new block test against a single block in the workflow. A block test freezes a set of inputs (either captured from a previous run or provided manually) and asserts something about the block’s output the next time it runs. The request body is two discriminated unions plus a required assertion:

target — what entity the test runs against. Today only block is supported; the field is shaped as a discriminated union so workflow-level targets can land later without breaking existing tests.
source — where the inputs come from. manual carries an explicit handle_inputs map; run_step references a previous workflow run plus the optional step inside it whose inputs to capture.
assertion — required. One assertion per test against one declared output handle (see Block Tests for the assertion shape and the available operators).

from retab import Retab

client = Retab()

# Manual inputs: hand-write the handle inputs the block should run with.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "manual",
        "handle_inputs": {
            "input-document-0": {
                "type": "file",
                "file_id": "file_invoice_q1",
            },
        },
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "total"},
        "condition": {"kind": "equals", "expected": 1234.56},
    },
    name="Q1 invoice total",
)

# Run-step inputs: replay the inputs the block ACTUALLY received in a run.
test = client.workflows.tests.create(
    workflow_id="wf_abc123xyz",
    target={"type": "block", "block_id": "block_extract_invoice"},
    source={
        "type": "run_step",
        "run_id": "wfrun_def456",
        "step_id": "block_extract_invoice",
    },
    assertion={
        "target": {"output_handle_id": "output-json-0", "path": "vendor.name"},
        "condition": {"kind": "contains", "expected": "Acme"},
    },
)

print(f"Test created: {test.id}")

{
  "id": "wfnodetest_hsLEQiM61ez9Piv147MWk",
  "workflow_id": "wf_abc123xyz",
  "organization_id": "org_123",
  "target": {
    "type": "block",
    "block_id": "block_extract_invoice"
  },
  "source": {
    "type": "manual",
    "handle_inputs": {
      "input-document-0": {
        "type": "file",
        "file_id": "file_invoice_q1"
      }
    }
  },
  "name": "Q1 invoice total",
  "assertion": {
    "id": "assert_xyz",
    "target": { "output_handle_id": "output-json-0", "path": "total" },
    "condition": { "kind": "equals", "expected": 1234.56 },
    "label": null
  },
  "assertion_schema_dep": {
    "schema_path": "total",
    "subtree_hash": "7d79dd764ab6548d",
    "depends_on_root": false
  },
  "assertion_drift_status": null,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "validation_status": "valid",
  "validation_issues": [],
  "latest_run_summary": null,
  "latest_passing_run_summary": null,
  "latest_failing_run_summary": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

Api-Key

string

header

required

Path Parameters

workflow_id

string

required

Query Parameters

access_token

string | null

operation_name

string

default:get_ready_gcp_settings

Body

application/json

block_id

string

required

name

string | null

assertion

AssertionSpec · object

Block-test assertion against one declared output handle.

target is the only supported shape: an output handle id and an optional relative path inside that handle's payload.

Show child attributes

handle_inputs

Handle Inputs · object

Show child attributes

run_id

string | null

step_id

string | null

Response

Successful Response

workflow_id

string

required

organization_id

string

required

block_id

string

required

block_type

string

required

string

captured_from

CapturedFrom · object

Show child attributes

captured_at

string<date-time> | null

name

string | null

handle_inputs

Handle Inputs · object

Show child attributes

handle_inputs_fingerprint

string

default:""

schema_fingerprint

string

default:""

validation_status

enum<string>

default:valid

Available options:

valid,

warning,

invalid

validation_issues

ValidationIssue · object[]

Show child attributes

created_at

string<date-time>

updated_at

string<date-time>

assertion

AssertionSpec · object

Block-test assertion against one declared output handle.

target is the only supported shape: an output handle id and an optional relative path inside that handle's payload.

Show child attributes

assertion_schema_dep

AssertionSchemaDep · object

Single-rule schema dependency for Level 2 drift detection.

Show child attributes

assertion_drift_status

enum<string> | null

Available options:

valid,

drifted,

broken

schema_drift

enum<string>

default:unknown

Available options:

none,

partial,

drifted,

unknown

schema_drift_detail

string | null

latest_run_summary

LatestBlockTestRunSummary · object

Show child attributes

latest_passing_run_summary

LatestBlockTestRunSummary · object

Show child attributes

latest_failing_run_summary

LatestBlockTestRunSummary · object

Show child attributes

Get Step List Block Tests

API Reference

Documentation Index

Authorizations

Path Parameters

Query Parameters

Body

Response