CLI to ALIGN test artefacts for any level of testing

Integration knowledge
as code.

SYZYGY is a CLI tool that standardizes how your integration knowledge is captured, versioned, and shared — turning scattered API specs, test scenarios, test data, and environment configs into a single, portable plugin.

Test at any level — component, integration, or E2E — using the same artefacts. No duplication. No drift. Every team, every environment, every test phase works from the same source of truth.

Start in plain English. Capture how each system should behave as a structured spec, and the AI assistants syz init configures turn it into runnable plugins, scenarios, and an always-current traceability matrix — from day one.

npm install -g syzs-cli
Read the quickstart

Requires Node.js 20+

01 The problem

Integration Knowledge Is Fragmented. That's Your Real Problem.

Most organisations carry their integration knowledge in five places at once: a Postman collection on one engineer's laptop, a Confluence page two years out of date, a custom test framework someone built and left behind, a folder of CI scripts no one owns, and the head of the senior engineer who is about to take a different job. None of those things are wrong. None of them are aligned.

The Framework Trap

Every team automates testing the same way: they build a framework first. Then the people who knew how the systems integrated leave, and the knowledge leaves with them. What follows is always the same pattern — a custom runner no one fully understands, a folder of "helpers" that grew organically, credentials stored in places they shouldn't be, a Confluence page two years out of date, and one engineer everyone defers to about which endpoint to call in what order. That engineer becomes a bottleneck. When that engineer leaves, so does the knowledge.

The Real Challenge Isn't Writing Assertions

The hard part of testing modern software has never been writing assertions. The hard part is where your integration knowledge lives: the endpoints, the request shapes, the order of operations, the negative-path expectations, the rules a manager calls "how we actually work." Frameworks let you write tests. They don't help you keep the knowledge that makes those tests worth writing.

SYZYGY: Integration Knowledge as a Durable Artifact

SYZYGY treats integration knowledge as the artefact. It packages that knowledge into one durable, versioned form — a plugin — and gives every developer, every test phase, and every environment the same source of truth. You version it (a git tag). You install it (syz install). You reuse it across every level of testing your team does, against every environment, by every developer. When the engineer leaves, the plugin stays.

The old loop
What SYZYGY replaces it with
  • What "correct" means lives in one person's head — written down nowhere concrete.
    Captured as schema-validated PLUGIN-GUIDE.yaml / DOMAIN.yaml, in plain language, before a plugin exists.
  • Build a framework first. Argue about folder conventions.
    One folder, .syz/. Convention over config.
  • Endpoints and payloads live in a doc, a Postman collection, or a senior engineer's head.
    A versioned plugin per integration. Installed via syz install.
  • Component, integration, e2e, UAT each get their own scripts.
    Same plugin, same scenarios — switch the environment file.
  • New team members onboard for weeks before writing a test.
    syz init lays down the framework. The AI assistant they already use is configured automatically.
  • When the integration owner leaves, the knowledge leaves.
    The knowledge is committed. Versioned. Reviewed in PRs like any other code.

02 The shift

A CLI for integration knowledge.

One binary. Nothing else to operate.

SYZYGY runs the whole testing lifecycle from one place — and it starts with knowledge, not code. The people who know what a system must do capture it in plain domain language as a concrete, schema-validated spec, before a single plugin exists. syz generate turns an API spec into a runnable plugin. Scenarios wire those plugins into tests. The runtime executes them deterministically and writes a report anyone can read. syz rtm ties every result back to the requirement it proves. The lifecycle below renders that path, stage by stage.

And it never drops you onto a blank page. syz init lays down a versioned knowledge layer under .syz/dossier/ — a directive router (SYZ-INDEX.md), a full CLI manual, a testing how-to, design guidelines, and guided DOMAIN.yaml / TEST-STRATEGY.md stubs — so the AI assistants you already use can help capture requirements and author scenarios from the very first command.

Underneath that lifecycle is a single Node.js CLI (syz, package syzs-cli) that runs declarative scenarios written in YAML against a set of versioned plugins that encode how your systems integrate. Scenarios, plugins, test data, and environment configurations all live in your git repo as YAML files. No server to operate, no database to provision, no central registry to publish to — everything runs locally or in any CI runner with Node.js 20+.

A scenario is a flow of step agents — craft, send, validate — and workflow agents that compose them, chaining into anything from a single-endpoint smoke check to a full end-to-end choreography. Each scenario writes an isolated, immutable execution ledger; every run produces a structured index.html report, a per-scenario debug.log, and an optional JUnit XML for CI. AI is pushed to its full potential exactly where authoring benefits from reasoning — drafting specs, payloads, and semantic checks — while execution, assertions, and the ledger stay fully deterministic, so verdicts never drift with model variability. The CLI is the only piece you install; everything else is plain text you commit to git.

  1. Authoring Capture PLUGIN-GUIDE.yaml · DOMAIN.yaml Describe how each system must behave, in plain language — before a plugin exists.
  2. Authoring Generate syz generate Turn an API spec into a complete, runnable plugin — deterministically.
  3. Authoring Author scenarios in YAML Wire plugins into declarative test flows your AI assistant drafts for you.
  4. Execution Execute syz run Resolve, send, validate — one deterministic lifecycle, every environment.
  5. Audit + Review Report index.html · ledger.json A self-contained report and an immutable ledger anyone can read.
  6. Audit + Review Trace syz rtm Every result tied back to the requirement it proves — a matrix that's always current.

Day one, .syz/dossier/ already ships the knowledge layer that supports the first three stages — so capturing requirements and authoring scenarios in plain language works from the very first command.

One binary

npm install -g syzs-cli — runs anywhere Node.js 20 runs. No server, no database, no central service.

Plugins in git

Share integration knowledge the way you share libraries. Versioned by tag, installed with syz install, pinned in dependency.json.

Scenarios in YAML

Declarative, diffable, reviewable in code review. Same scenario across every test phase — switch the environment file.

AI where it earns its keep

Deterministic runtime; bring any OpenAI-compatible provider for the parts that genuinely benefit from reasoning.

03 How it works

A small, sharp model. Three things.

The Execute and Report stages of the lifecycle, up close. Plugins hold the knowledge — agents, templates, models, fixed test data, and a guide that explains it all. Scenarios describe the flow. Environments name the infrastructure under test. The CLI runs them, deterministically.

Plugin

A versioned bundle of integration knowledge for one system — its step agents (which craft payloads, send requests, and validate responses), templates (for request bodies, attachments, and other outbound artefacts), models (input contracts that document and validate every step agent's inputs), fixed test data, and README that depicts all the business, technical, logical or any other knowledge of the system required for testing. Owned by the team that owns the integration, kept in git, tagged like a library, and installed with syz install.

Scenario

A YAML file that names a flow — a sequence of step agents a plugin exposes. The same scenario can be reused across test levels (a mock during component testing, staging during integration, a production-like environment during UAT), or new scenarios can be authored for a new scope, pulling in whichever plugins are needed with syz install.

Environment

A YAML file that names the infrastructure involved — base URLs, credentials (via env vars or secret-manager-rendered files), and any per-system config or environment specific test data. Switching environments is switching one CLI flag.

AUTHORING what you commit
plugins · agents · templates · models · data.yaml · README.md scenarios · craft · send · validate · workflow environments · base URLs · credentials · configurations · settings
EXECUTION deterministic
resolver · runtime data builder · ledger / env / data / outline / ctx.var / os-env-var / {{ ai: }} references · leverages AI for complex data on demand payload builder · dynamic payload generation powered by Nunjucks and your data inputs. executor registry · HTTP today · built to plug in Kafka, MQ, SFTP, SSH, SQL, NoSQL, key-value, gRPC, cloud, and browser executors — without touching the runtime assertion factory · json · text · http with optional AI assistance and extensibility
AUDIT immutable
ledger.json · each step's request/response entries · sensitive data masked debug.log · per-scenario execution trace index.html · run summary dashboard · per-scenario expandable details · single-stop for any execution detail execution.json · run summary metadata · per-scenario status index junit.xml · CI-friendly test results · optional

What happens when you run

command
syz run --suite <path> --env <name> [options]
--suite required path to a scenario file or directory of scenarios to run
--env required name matching a file in .syz/environments/ — sets base URLs, credentials, config
  1. 01

    Load

    Zod-validated — schema mismatch aborts before any execution begins

    Plugins from .syz/plugins/ (local) and .syz/plugins.installed/ (git-installed), the scenario(s), the environment, and the optional AI API config — Zod-validated, every file.

    reads plugins/ plugins.installed/ scenario env.yaml ai-api.yaml
  2. 02

    Pre-flight

    All-or-nothing — no partial execution begins with an unresolved name

    The pre-flight checker walks the scenario's flow and confirms every step or workflow agent referenced (including those nested inside workflow agents) exists in a loaded plugin. No execution begins until every name resolves.

    checks step agent names workflow agent names nested references
  3. 03

    Execute

    Three agent types. One shared lifecycle. Distinct middle phase.

    The flow runner iterates step by step. Every step agent — regardless of type — runs the same outer lifecycle: input resolution, then the agent's specific execution, then a ledger write. What changes is the middle phase. A craft step agent resolves its inputs, renders the payload via a Nunjucks template or an AI crafter, and optionally writes the artifact to disk for a downstream send. A send step agent resolves its inputs, constructs the full request payload from its Nunjucks template, and dispatches it to the target system via the executor — the response envelope is what downstream steps reference. A validate step agent resolves its inputs (including the response passed from the ledger), runs every declared check through the assertion engine, and writes each verdict to the ledger.

    craft
    resolve inputs render template / AI crafter write artifact to disk ledger
    send
    resolve inputs build payload via template execute call to server ledger
    validate
    resolve inputs run assertions on response ledger
  4. 04

    Record

    Immutable — sensitive fields are masked at write time, not after

    Every step writes an immutable, indexed entry to the scenario's ledger. Sensitive fields declared in the agent YAML are masked on write. Output shortcuts resolve via JSONPath against the response and become {{ ledger.<agent>.outputs.<field> }} references for downstream steps.

    writes ledger entry masked fields {{ ledger.x }}
  5. 05

    Report

    Opens via file:// — no server, no network, no dependencies

    The reporter writes index.html (clickable, embedded, opens with file://), per-scenario debug.log (plain-text phase trace), per-scenario ledger.json (the audit artefact), execution.json (run-level index), and optionally a JUnit XML.

    emits index.html debug.log ledger.json execution.json junit.xml?

04 Core capabilities

What you get on day one.

Every capability below is shipped today.

  1. 4.1
    Capture · Trace

    Requirements as a concrete spec — authored by AI, traced automatically

    Document what each system must do. Link tests to it. Get a matrix that's always current.

    The people who know what "correct" means — product owners, business analysts, integration owners — capture it as schema-validated YAML: PLUGIN-GUIDE.yaml per integration, DOMAIN.yaml for the cross-service journeys. It's written in plain domain language with any AI assistant out of the box, before a single plugin exists — a concrete, structured spec with required fields and a known vocabulary, not free prose, so it stays consistent across people and sessions and is validated by syz lint. Every requirement carries a stable ID. Link any scenario, outline, row, or step to the requirements it exercises with covers:, and syz rtm generates a Requirements Traceability Matrix on demand — a derived report, like the run report, never maintained by hand. --strict fails CI on any uncovered requirement or dangling link; --lastrun annotates each requirement with its latest execution outcome.

  2. 4.2
    Execute

    Same scenarios, every environment

    Author once, run against a mock during component testing, staging during integration, and a production-like environment during UAT.

    --env <name> selects the environment file. Plugins read system config from env[pluginName] — base URLs, tokens, timeouts — so switching environments is switching a flag. Cross-references between systems ({{ env.shared.api_key }}) are resolved at load time with cycle detection, so a misconfigured env fails before any execution begins. {{ os-env-var:NAME }} is the inline resolver for OS environment variables — commit env files safely and inject secrets from a vault or CI secret store. Every resolved value is automatically registered and masked across all artefacts (stdout, debug log, ledger, HTML), composing with path-based sensitive_fields masking.

    The environment file's counterpart is the plugin's data.yaml — the test data that stays fixed across environments (canonical payloads, reference IDs, sample inputs), addressed in templates as {{ <plugin>.data.x }}. Environment files hold what changes per environment; data.yaml holds what doesn't. Together they form the full test-data substrate, split along the only line that matters: does the value vary with where you run, or with what you test.

  3. 4.3
    Author

    Plugins are shared like libraries

    Versioned in git. Installed by tag. Pinned in a manifest. The same workflow your team already uses for code.

    syz install performs a shallow, sparse checkout — git clone --no-checkout --depth 1 --branch <tag> then git sparse-checkout set — and copies only the plugin's folder into .syz/plugins.installed/. No central registry, no publish workflow, no proprietary lock-in. .syz/dependency.json records every dependency by name, URL, and version — committed to source control so every team member and CI runner reproduces the same set. Monorepos with many plugins install efficiently because only the named plugin folder is transferred.

  4. 4.4
    Audit + Review

    Every run is fully traceable

    Open the report. Click into a failing step. See exactly what was resolved, what was sent, what came back, and what the assertion concluded.

    Every step's four-phase trace is written to debug.log as plain text (identical to what streamed to the terminal) and embedded into index.html as structured data. The HTML report opens via file:// double-click — no server, no network. Two masking mechanisms compose: path-based sensitive_fields declared on the agent, and a run-scoped secret registry that automatically masks every value resolved from {{ os-env-var:... }} — both apply everywhere (stdout, debug log, ledger, HTML). Each scenario gets its own isolated ledger, so {{ ledger.x }} references never cross scenario boundaries and a failing scenario never corrupts a passing one.

  5. 4.5
    Execute

    Assertions that match what humans check

    Equality, regex, schema, range, count, deep array predicates, expression — and an ai operator for semantic rules a deterministic check can't express.

    The assertion engine supports json, text, and http assertion types, each with its own valid operators (full list in the technical depth section). Every assertion result records what rule produced the verdict — type, operator, and path? are first-class fields on AssertionResult — so the ledger answers "did this pass because of equals or contains?" without re-running the test. The expression operator runs in a sandboxed VM context for JS-power escape-hatch checks across multiple response fields. The ai operator delegates to your configured provider with a structured-output prompt and records the model's reasoning in the assertion result.

  6. 4.6
    Author

    Parameterised testing — and run exactly the slice you want

    Outline scenarios — same flow, an array of examples, one isolated execution per row. Then select what runs.

    examples: makes a scenario file an outline. Each row becomes an independent execution with its own ledger and results folder. Failing rows do not halt other rows — you see which inputs fail and which pass in a single run. Outline values support every other resolver ({{ env.x }}, {{ <plugin>.data.x }}, {{ ai: ... }}) so example rows can themselves be generated. Tag scenarios and rows with tags: and select with --tag; pick named outline rows with --example; or curate a release playlist as a suite manifest (.syz/suites/<name>.suite.yaml) and pass it to --suite. The same selectors run on syz run and syz lint, so a lint previews the exact set a run would execute.

  7. 4.7
    Generate

    Generate plugins from what you already have

    Point syz generate at an OpenAPI spec or a Postman collection — or answer a short interactive prompt. Get a complete, runnable plugin.

    The generator is deterministic — no AI in the path, no network call required, always reproducible. It parses the source, builds a normalised SourceModel, and emits the full plugin: every send step agent, every validate step agent, every input model, every Nunjucks template, the plugin's data.yaml, a scaffolded PLUGIN-GUIDE.yaml, and a happy-path sample scenario. Multipart endpoints with text content types are scaffolded as craft → send → validate; binary multipart endpoints get a filePath send step agent and validate step agent. OpenAPI and Postman ship today; the same --from interface is built to take more formats (see Roadmap).

  8. 4.8
    Foundation

    AI where it earns its keep, deterministic everywhere else

    Plug in any OpenAI-compatible model. The runtime never drifts.

    AI is opt-in and provider-agnostic. .syz/ai-api.yaml configures a base_url, a model, and an api_key (use {{ os-env-var:NAME }} for env-backed keys — resolved at load time, auto-masked in all artefacts). It works against Anthropic, OpenAI, Azure, vLLM, or any compatible gateway. The resolver, executor, assertion engine, and ledger remain deterministic — model variability never propagates into test verdicts. If AI isn't configured, only the features that use it ({{ ai: }} resolver, crafter: ai, operator: ai) fail — and they fail with a single AI_CONFIG_INCOMPLETE error that names every missing field at once.

    A note on AI output. AI-generated artefacts — drafted payloads, resolved inputs, and AI-evaluated verdicts — are non-deterministic. Treat them as a starting point and review them before you rely on them.

  9. 4.9
    Foundation

    Your AI coding assistant, configured for you

    syz init writes a framework-aware context file for every major AI tool. Open the project; the assistant already knows.

    Claude Code, Cursor, GitHub Copilot, Windsurf, Continue.dev, Amazon Q, JetBrains AI, Gemini Code Assist, and Aider all receive a pointer file at the path each tool auto-discovers. Behind those pointers is a versioned knowledge layer under .syz/dossier/ — a lean directive router (SYZ-INDEX.md) plus a full CLI manual, design guidelines, a testing how-to, and an AI-risk notice — all owned and overwritten by the framework on update, so every assistant authors against the current contract. No prompt engineering, no copy-pasted docs, no drift.

    • Claude Code
    • Cursor
    • Copilot
    • Windsurf
    • Continue
    • Amazon Q
    • JetBrains AI
    • Gemini Code Assist
    • Aider
  10. 4.10
    Audit + Review

    CI-ready out of the box

    JUnit XML on demand, deterministic exit codes, no browser opened unless asked.

    syz run --reporter junit writes a JUnit XML at the default path or to any path with --output. The format is consumed natively by GitHub Actions, GitLab CI, Jenkins, CircleCI, Buildkite, and Azure DevOps — inline PR test panels and trend tracking work without further configuration. Exit code is 0 only when every scenario succeeded; 1 on any failure; 130 on SIGINT. --continue-scenario-on-failure runs every step past a failed assertion (the verdict still fails the run) for full-picture CI reports. The live progress panel is opt-in (--live-stats) — CI never opens windows.

  11. 4.11
    Execute

    Deterministic control over time and eventual consistency

    A fixed wait when you need one. A bounded retry when the system is eventually consistent.

    syz.wait is a built-in step that pauses a flow for a fixed number of milliseconds — deterministic, never an AI call. For asynchronous systems, add a poll: block to a workflow step: it re-runs the workflow until its validations pass or a bound trips (max_attempts, optional interval_ms, linear backoff_ms, timeout_ms). Only a failed verdict retries; a real fault breaks out immediately. Convergence is testable without flaky sleeps.

05 Quickstart

Five commands. First green run.

Real commands, real flags, real file paths. Nothing reads # placeholder.

You need Node.js 20+ and a git repo (any). Paste everything below.

  1. 1

    Install

    npm install -g syzs-cli
  2. 2

    Initialise the project structure

    syz init

    Creates the .syz/ directory, the dossier/ knowledge layer, and a context file for every supported AI tool. It's explicit and idempotent — safe to re-run, and re-running after a CLI upgrade refreshes the framework rules in place. It never overwrites files that are yours: .syz/README.md, dossier/DOMAIN.yaml, dossier/TEST-STRATEGY.md, and each plugin's PLUGIN-GUIDE.yaml.

  3. 3

    Acquire a plugin

    Three ways. Pick the one that fits your situation.

    syz install https://github.com/syzs-code/payments-plugin.git@v1.2.0 \
  --plugin payments

    For an OpenAPI spec with more than ten operations you'll be prompted to confirm before any files are written. Use --dry-run to preview the file list without writing.

    Now write the environment file that points the plugin at your system, and the scenario that describes what to test:

    .syz/environments/local.yaml

    name: local
production: false
payments:
  base_url: "http://localhost:3000"
  token: "{{ os-env-var:PAYMENTS_TOKEN }}"  # resolved at load time; value auto-masked everywhere
  timeout_ms: 5000                           # optional — default 30000

    Export the token in your shell or your CI's secret store:

    export PAYMENTS_TOKEN="dev-token"

    .syz/scenarios/e2e/checkout.yaml

    name: "Checkout — successful order"
level: e2e
environment: local
plugins:
  - name: payments
    version: "1.0.0"

flow:
  - type: send
    agent: payments.step_send_order
    inputs:
      userId:   "u-001"
      amount:   100
      currency: "GBP"

  - type: validate
    agent: payments.validate_order_response
    inputs:
      response:        "{{ ledger.payments.step_send_order.response }}"
      expected_status: 201
  4. 4

    Lint

    Pre-flight: confirm the scenario has everything it needs before running.

    syz lint --env local
  5. 5

    Run

    syz run --suite .syz/scenarios/e2e/checkout.yaml --env local

    You'll see each step stream to the terminal phase-by-phase, then a one-line summary. Open the report:

    open .syz/results/run-2026-04-25T09-12-34-567Z/index.html
    run-2026-04-25T09-12-34-567Z
    3 success 0 failed 12.5s
    ✓ e2e/checkout — Checkout — successful order 570ms
    ✓ e2e/refund — Refund — invalid order 275ms
    ✓ sendpayments.step_send_order 450ms
    ✓ validatepayments.validate_order_response 120ms

    Self-contained index.html — opens via file://, no server.

    …or use --run-name to name the run yourself:

    syz run --suite .syz/scenarios/e2e/ --env staging --run-name sprint-42-regression

    That's it. The same scenario runs against staging, UAT, or production by changing the --env flag and the matching environment file.

06 Anatomy of a plugin

What's in a plugin.

A folder — step agents, workflow agents, templates, models, test data, and a schema-validated integration guide. All YAML and Nunjucks. No code generation, no DSL, no surprises.

A plugin is a directory under .syz/plugins/<name>/ (if you authored it locally) or .syz/plugins.installed/<name>/ (if syz install fetched it for you). Both shapes are identical.

  • craft step agent renders a local artefact (XML, CSV, SWIFT MT103) via Nunjucks or AI, optionally writing the result to disk for a downstream send step agent.
  • send step agent declares an executor (http), an input contract, a payload template, optional named outputs, and a list of sensitive fields.
  • validate step agent declares an input contract and a list of checks — JSONPath, text, HTTP-metadata, with operators that include ai.
  • workflow agent composes other step agents with input wiring, accepting field-level overrides from the scenario that calls it.
  • models contains YAML input contracts — a named list of typed fields each agent accepts. Referenced by input_model: in craft, send, and workflow agents; consumed at runtime for validation and by AI agents writing scenarios against the plugin.
  • templates contains Nunjucks .njk files that render the full request — method, URL, headers, body — with access to resolved inputs, environment values, and plugin data. Referenced by template: in craft and send agents.
  • data.yaml holds the test fixtures that don't change with the environment — canonical payloads, reference IDs, sample inputs — addressed in templates as {{ <plugin>.data.x }}.
  • PLUGIN-GUIDE.yaml is the plugin's integration knowledge as schema-validated YAML: each operation's behaviour, business and logical rules, error semantics, and requirements with stable IDs. User-owned, scaffolded on generate, shipped with the plugin via syz install, and read by AI agents authoring scenarios.
.syz/plugins/payments/
├── plugin.yaml                    # name + version, two fields
├── PLUGIN-GUIDE.yaml              # integration knowledge — schema'd YAML, ships via syz install
├── CLAUDE.md                      # one-line pointer to PLUGIN-GUIDE.yaml
├── agents/
│   ├── step_send_order.yaml       # a send step agent
│   ├── validate_order_response.yaml
│   └── workflow_checkout.yaml     # a workflow agent that composes the two
├── models/
│   └── order_request.yaml         # input contract for the send step agent
├── templates/
│   └── create_order.njk           # full Nunjucks runtime
└── data.yaml                       # static test data, shared across environments
plugin.yaml 
plugin: payments
version: 1.0.0

07 Technical depth

Learn to evaluate, not to operate.

You never have to learn how to code to use SYZYGY. The CLI ships all its knowledge directly to the AI code assistants you already use — they have everything they need to author, generate, and maintain your scenarios and plugins on your behalf. The technical detail below serves a different purpose: it equips you to read what runs, understand why a test failed, monitor what the runtime produces, and customise or improve generated output when the need arises. That context keeps you in control without requiring you to build from scratch.

If you're new to the tool, the step-by-step Tutorial is a better starting point — it walks through everything hands-on, from cli setup to a working plugin.

08 Who it's for

Where SYZYGY earns its keep.

It starts with the people who own what "correct" means — and reaches every team that has to prove it. Four shapes of team; if yours rhymes with any, this is the tool.

Start here

01 / Product owner · BA · SME

The people who own what the system is supposed to do — and rarely write code

Document each integration's behaviour and the cross-service journeys as a concrete, schema-validated spec — PLUGIN-GUIDE.yaml and DOMAIN.yaml — in plain domain language, drafted with any AI assistant out of the box, before a single plugin exists. Every requirement gets a stable ID; covers: links the tests to it; syz rtm proves the coverage. The knowledge that used to live in one person's head becomes a reviewed, versioned, traceable artefact.

02 / Platform team

The platform team owning an API used by twelve other teams

You own a payments API (or an orders API, or an auth API). Twelve other teams call it. You spend a non-trivial fraction of every sprint answering "what's the right payload for endpoint X" and "we got a 400, what does that mean". Today, every consumer team has their own ad-hoc test setup. With SYZYGY, you publish a payments plugin — one git repo, one syz install line for every consumer. Endpoints, payloads, validators, negative-test expectations, common workflows — all versioned, all in one place, all reused. New consumers onboard in an afternoon. Breaking changes propagate via a version bump.

03 / Integration team

The integration team running a multi-environment test stack

You have component tests against mocks, integration tests against a shared staging instance, end-to-end tests against a production-like environment, and UAT against a stakeholder-facing slice. Today, you maintain four different test suites. With SYZYGY, you maintain one set of scenarios and four environment files. Same plugins, same scenarios, different --env flag. When the API changes, you update the plugin in one place, bump the version, and re-pin in every consumer's dependency.json.

04 / QA lead

The QA lead who needs CI-friendly tests and trust in the results

You need exit codes that mean something, JUnit XML that GitHub Actions and Jenkins read natively, deterministic verdicts, and audit artefacts you can hand to compliance. With SYZYGY, every run produces an immutable ledger, a phase-by-phase debug log, a JUnit XML (--reporter junit), and a requirements-traceability matrix (syz rtm, with --strict as a CI gate). Live progress panels are opt-in (--live-stats) for your local executions. Sensitive fields are masked everywhere, including the report. The exit code is 0, 1, or 130 — and you can rely on it.

09 Roadmap

Same model. More surfaces.

What ships today runs over HTTP. The architecture was built so new protocols, sources, and surfaces drop into the same registry without changing the runtime, the ledger, or how you author a scenario. The items below are planned, not yet shipped — everything in Sections 01–08 is.

More executors. The executor registry takes new protocols behind one native-outcome contract: every executor captures its system's real response, and your validate steps decide pass or fail — so the way you author and assert a test never changes as the protocol does. Planned executors: Kafka (producer + consumer), message queues (publish + consume), SFTP (upload + download), SSH, SQL databases, NoSQL databases, key-value stores, gRPC, WebSocket, cloud services (object storage, queues, pub/sub), and a browser executor — with the priority order driven by what teams actually ask for. Stateful executors use named connection handles — open once, reuse across steps, torn down at scenario end; eventual-consistency systems are already served by the shipped poll: and syz.wait primitives.

More generation sources. syz generate reads OpenAPI and Postman today. The same --from interface and source registry are built to extend — each new format is just a new parser, with no change to the deterministic builder. On the list: AsyncAPI, WSDL, XSD, cURL, RAML, API Blueprint, GraphQL SDL, GraphQL Introspection Schema — and more on demand.

The point of the roadmap is the inverse of a feature list: the surfaces grow, the model doesn't. A team that learns to author one HTTP scenario today authors a Kafka or SQL scenario the same way tomorrow — same agents, same resolvers, same ledger, same report.

Aligned

Install it.

One command. Node.js 20+. No infrastructure to stand up.
The first green run is five commands away.

npm install -g syzs-cli