Runs on your machine
npm install -g syzs-cli — anywhere Node.js 20 runs. No server, no account, no telemetry. Payloads, credentials and reports never leave your network.
Requirements traceability for regulated teams
Prove your tests
cover your requirements.
Requirements and tests live in one versioned artefact — so drift shows up as a failing run, not a surprise in an audit.
Your requirements sit in Jira and a Word document. Your tests sit in code. Nothing connects them — so the traceability matrix gets rebuilt by hand before every audit, and is out of date the week after.
SYZYGY couples them. Business owners author requirements in plain language; tests are generated from those requirements and reviewed by a person before anything is committed.
Execution is deterministic — the same inputs produce the same run and the same evidence, every time. The matrix is a by-product of the run, not a document somebody maintains.
- Deterministic by construction — same inputs, same evidence, nothing to configure
- Runs air-gapped — no data leaves your network
- No code required to author requirements
~/payments-api
syz · latest
syz run across 15 scenarios, then
syz rtm deriving the matrix — captured end to end.
A terminal recording in four parts. First, a file called DOMAIN.yaml
is displayed, holding a requirement written in plain English: “A paid order
settles and the customer is notified”, with its given/when/then conditions,
the business rules that apply, and explanatory notes. Second, the command
syz run executes a suite of fifteen test scenarios against a payments
service; each step shows the request sent, the response received, and the
assertions checked, finishing with “15 passed of 15” in 5.08 seconds.
Third, the command syz rtm reports zero uncovered requirements and
zero dangling references, then prints the Requirements Traceability Matrix: a
table of seven requirements, each paired with the test scenarios that cover it and
the outcome of each. The recording ends holding on that completed matrix.
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 Artefact
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 vs. what SYZYGY replaces it with
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 initlays 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 What it is
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.
Underneath it is a single Node.js CLI (syz, package syzs-cli) that runs declarative YAML scenarios against versioned plugins that encode how your systems integrate. Scenarios, plugins, test data, and environments all live in your git repo as plain text — no server, no database, no central registry, and nothing about your work leaves your network: no cloud, no account, no telemetry. That is what makes SYZYGY usable inside a bank, a hospital, or a government department without a vendor security review.
Plain YAML, executed exactly. Every value in a run comes from a committed file or a previous step, so the same scenario reaches the same verdict every time. Your AI assistant helps you author; what it drafts is reviewed and committed like any other code.
Runs over HTTP today; the executor registry is built so Kafka, SQL, SFTP, gRPC and more drop in without changing how you author a test — see the full roadmap.
The SYZYGY lifecycle, from requirement capture to requirements traceability
-
Authoring Capture PLUGIN-GUIDE.yaml · DOMAIN.yaml Describe how each system must behave, in plain language — before a plugin exists.
-
Authoring Generate syz generate Turn an API spec into a complete, runnable plugin — deterministically.
-
Authoring Author scenarios in YAML Wire plugins into declarative test flows your AI assistant drafts for you.
-
Execution Execute syz run Resolve, send, validate — one deterministic lifecycle, every environment.
-
Audit + Review Report index.html · ledger.json A self-contained report and an immutable ledger anyone can read.
-
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.
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.
Authored with AI, executed exactly
Your assistant authors against a versioned knowledge layer; you review and commit. From there the runtime replays exactly what you committed — same inputs, same request, same verdict, forever.
03 The artefacts
Everything above, as it actually ships.
Five real captures from genuine runs — not mockups. They run in lifecycle order: a requirement written in plain language, and four artefacts later, that same requirement proven by a test. Click any one to see it full size.
-
01 · CaptureA product owner writes the requirement in plain language — before the code exists, and independent of any spec generated from it. “A Product Owner should be able to read and update this file, before a single plugin exists.” This is the baseline everything else is measured against. -
02 · GenerateThe OpenAPI spec generates the mechanical scaffolding: 22 procedures across seven operations. It does not generate requirements — those came from stage one. -
03 · ExecuteEvery run writes this. Opens with a double-click; no server. -
04 · DebugA failed assertion, with what was sent, what came back, and which rule decided. -
05 · Trace syz rtmrenders the matrix from the run that just happened. The requirement, the test that covers it, the run that executed it, and the request/response that proves it — four artefacts, all in git.
04 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.
Where it bites hardest. SYZYGY earns its keep fastest in regulated, REST-heavy organisations — financial services, healthcare, insurance, government — where two costs are already being paid in full: proving to an auditor which test covers which requirement, and losing a decade of integration knowledge every time a senior engineer resigns. Teams outside those industries get the same mechanics; teams inside them have a budget line for the pain.
Start here
For the person who has to hand evidence to an auditor.
You need to show that every requirement has a test, that the test ran, and that it passed — in a form somebody outside the engineering team can read. Today that means a spreadsheet somebody rebuilds by hand, and a quiet hope that nothing has changed since.
SYZYGY produces the matrix as output of the test run itself. Exit codes, JUnit XML, deterministic verdicts, and a rendered traceability matrix that is current because it cannot be anything else.
Every run produces an immutable ledger, a phase-by-phase debug log, JUnit XML (--reporter junit), and the matrix from syz rtm — with --strict as a CI gate that fails the build on any uncovered requirement. Every artefact is a plain file in git, reviewable in a pull request, so the evidence pack for a release is a commit range, not a screenshot folder assembled the week before the audit. Sensitive fields are masked everywhere, including the report. Live progress panels are opt-in (--live-stats).
The exit code is a per-verdict signal CI can branch on — 0 all passed, 1 a check failed, 2 bad input or setup, 3 an upstream system faulted, 4 no verdict delivered, 130 interrupted.
Also used by
-
Product owner · BA · SME
Own what the system is supposed to do, without writing code. Behaviour and cross-service journeys captured as schema-validated
PLUGIN-GUIDE.yaml/DOMAIN.yamlin plain domain language, before a single plugin exists — with stable requirement IDs thatcovers:links tests to. -
Platform team
Own an API a dozen other teams call. Publish one
paymentsplugin; every consumer adds onesyz installline. Breaking changes propagate via a version bump. -
Integration team
Run a multi-environment test stack. One set of scenarios and four environment files instead of four suites — same plugins, same scenarios, different
--env.
05 Straight answers
The questions you're actually asking.
Cost, licence, data, maturity, and how this differs from the tool you already use. No prose to wade through.
-
Yes, unconditionally. Every value in a run resolves from a committed file or a previous step's recorded output, and the resolver, executor, assertion engine and ledger are all exact. The same inputs produce the same run and the same evidence, every time — on the hundredth run as on the first. There is nothing to configure to make that true and no mode in which it stops being true.
-
Nowhere. There is no SYZYGY cloud, no account, and no telemetry — nothing about you, your systems, or your tests is collected. Payloads, credentials, responses and reports stay on the machine that ran them. The CLI makes exactly three kinds of outbound call, and you control all three: your systems under test, your git remote on
syz install, and a single npm-registry version check that sends no data about you, is dormant in CI, and is disabled withSYZ_NO_UPDATE_CHECK=1. That is the complete list. -
Yes. SYZYGY runs entirely on your machine or your CI runner — there is no hosted service to reach, no account, no telemetry and no phone-home. The only outbound calls it makes are to your own systems under test and your own git remote, plus a single npm version check that sends nothing about you and is disabled with
SYZ_NO_UPDATE_CHECK=1. Point it at an isolated network and everything works. -
No, and that's a design goal rather than a slogan.
syz initconfigures the AI assistant your team already uses with the full framework contract, so requirements capture and scenario authoring happen in plain language — see the AI-assistant capability on the depth page, and the plain-language playbook in the dossier. The artefacts themselves are plain YAML, executed deterministically. What you do need is someone comfortable reading YAML when a test fails: the artefacts are designed to be legible, not opaque. -
Yes — and keep it. Jira, Azure DevOps Boards, Confluence, Linear, monday.com, or a formal tool like Jama Connect or IBM DOORS are built to capture and triage work, and SYZYGY doesn't replace planning. Two problems, though. Mapping those tickets to the tests that prove them is manual, and deriving a requirements-traceability matrix from them is ongoing, hand-maintained effort. And those boards are organised around teams, not systems — scrum, squad, project. When a project closes or the org restructures, that work is archived; finding one system's requirements in an ocean of tickets, then migrating years of work, is heavy lifting few people ever finish. You end up with tests and no record of why each one exists.
SYZYGY captures requirements as schema-validated artefacts tied to the system —
PLUGIN-GUIDE.yamlper integration,DOMAIN.yamlfor cross-service journeys — each carrying a stable id (REQ-…), versioned in git and linked to tests withcovers:from day one.syz rtmderives the matrix on demand, never by hand.And nothing is orphaned from where it started. Record the originating ticket — its id or URL — in the requirement's
referencesfield, and tag that ticket with the SYZYGYREQ-…id in your tracker: the two now point at each other, so anyone can trace a test back through its requirement to the original ask, and forward again. Unlike the ticket, that cross-reference lives in git history — it survives the requirement changing, the project closing, or the board being archived. Keep your planning tool for triage; SYZYGY is where the durable, system-aligned, test-linked requirement record lives. -
Nothing. The CLI is free to install and use — no paid tier, no seat count, no usage limit, and no trial clock. That includes use inside a commercial, for-profit company: a bank automating its integration testing pays nothing.
The one boundary is monetising the software itself. You may not resell it, host it for third parties, offer it as a service, or use it to build a competing product. Use it as intended, free, forever; don't repackage it as your own. Anything outside that, email enquiry syz.sh.
-
It's pre-1.0, early access, and honestly labelled. The execution model, ledger, reporting, and traceability are shipped and stable — everything shown on this site works today. What's not there yet is protocol breadth: HTTP is the only executor, with Kafka, SQL, SFTP and the rest on the roadmap and prioritised by what teams actually ask for. Sensible move today is a single-team pilot, not an org-wide rollout.
-
BDD's promise is one shared, business-readable spec. In practice, the pressure to reuse and optimise step definitions bends the
Given/When/Thento fit the technical flow — open your.featurefiles and ask honestly how much a non-technical domain owner can still read. The business language and the automation are welded into the same file, and the automation usually wins.SYZYGY splits them cleanly. Requirements are the business-language layer —
PLUGIN-GUIDE.yamlrecords each behaviour as plain-Englishgiven/when/then, owned by the people who know the domain. Tests are the technical layer — scenarios in YAML, written however they need to be — and they simply link back to the requirements they exercise withcovers:.syz rtmthen shows precisely which test covers which requirement. Domain owners write requirements in plain language; engineers write tests without contorting them into a business-readable DSL. Neither side compromises to satisfy the other. -
The API-testing landscape is crowded and mostly free, and every tool in it is good at calling an API and asserting on the response:
- Postman · Insomnia · Bruno — API clients: explore endpoints, build collections, script assertions (Postman's Postbot even drafts them from the response it just saw).
- SoapUI · Karate · REST Assured — functional API test frameworks and DSLs.
- Pact — consumer-driven contract testing.
- k6 · JMeter · Gatling — load and performance.
- Schemathesis · Dredd — spec-conformance and property testing.
Each is strong at its job. But they all start from the call, and at best codify the behaviour they just observed — there's no requirement to trace back to. SYZYGY isn't another entry in that list: it treats integration knowledge as the artefact. Requirements are first-class and schema-validated (
PLUGIN-GUIDE.yaml/DOMAIN.yaml); tests link to them withcovers:, andsyz rtmderives the traceability matrix. Plugins are versioned and installed across your org like libraries, execution is deterministic, and nothing syncs to a vendor cloud. Keep the client you like for ad-hoc calls — SYZYGY is the durable, provable layer underneath. -
An AI that writes tests from your code tells you what the code does. SYZYGY proves the code does what a person said it should. That is the whole distinction, and it survives however good the model gets: a test derived from the implementation cannot detect that the implementation is wrong, because it agrees with it by construction. There is nothing independent to check against.
Two consequences follow. Generation drifts: ask twice and you get two different shapes, and you still own and maintain whatever it produced.
syz generateis deterministic — reproducible on every run — and it emits a complete framework (runtime, immutable ledger, HTML + JUnit reporting, and the RTM), so the framework is off your plate, not something a model reinvents per prompt. And the knowledge takes the big seat: raw model-written scripts bury what the system is supposed to do inside the script, where it drifts and can't be traced. SYZYGY inverts that — testing starts from a requirement a person wrote, as a durable, schema-validated artefact (PLUGIN-GUIDE.yaml/DOMAIN.yaml), and the tests derive from it and trace back to it withcovers:. The model still helps you author, but against a versioned contract, with deterministic execution and a matrix proving coverage — not a pile of scripts no one owns. -
Deliberately. SYZYGY is free to use, but proprietary — the source isn't public and it isn't open to community forks. That's a stewardship choice, not a commercial one. The method underneath it — knowledge as the artefact, every requirement aligned to a result — is easy to dilute, and we've watched respected test frameworks lose their way once they fragmented into a dozen incompatible flavours, each drifting from the intent that made the tool worth having.
We'd rather nurture SYZYGY carefully, shaped by how real teams use it and what they tell us, than optimise for how many variants exist. Even the finest tool rusts into a liability when it's wielded without care — and the real world offers no shortage of examples. Free to use, yes; free to fragment, no. Ideas, needs, and requests genuinely steer it — that's what support syz.sh is for.
-
It's not a load-testing tool, not a mocking framework, not consumer-driven contract testing, not UI/browser automation today, not a hosted service, and not an API client — keep your GUI for ad-hoc calls.
Though today it runs API and contract testing over HTTP — that framework is complete and shipping — with Kafka, message queues, UI/browser automation and more on the roadmap. So you can use it as a testing tool, and you're welcome to. But it isn't designed to replace the testing tool you already have.
The whole design idea is bigger than testing: preserve what your organisation knows and prove your systems behave as they're expected to. Testing capability of SYZYGY is to prove that your knowledge is implemented as intended. In short — align your every artefact, from Requirements to Results.
Aligned
Install it.
One command. Node.js 20+. No infrastructure to stand up.