asyncapi-parser
/asyncapi-parser
Parses AsyncAPI 3.x specs and generates Drift test cases from them. Use whenever the user wants to generate, write, or scaffold Drift tests from an AsyncAPI spec — especially when the spec contains complex message schemas: oneOf/anyOf/allOf, discriminators, polymorphism, $ref chains, or multiple message variants. Use when the user wants to test async event-driven services (Kafka, SNS, SQS), when they ask to "create tests for a channel", "cover all message variants", "generate test cases from the AsyncAPI spec", or says anything like "each viable combination of messages". Use when the user is t
- Author
- pactflow ↗
- Repository
- pactflow-agent-skills ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 12
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Parses AsyncAPI 3.x specs and generates Drift test cases from them. Use whenever the user wants to generate, write, or scaffold Drift tests from an AsyncAPI spec — especially when the spec contains complex message schemas: oneOf/anyOf/allOf, discriminators, polymorphism, $ref chains, or multiple message variants. Use when the user wants to test async event-driven services (Kafka, SNS, SQS), when they ask to "create tests for a channel", "cover all message variants", "generate test cases from the AsyncAPI spec", or says anything like "each viable combination of messages". Use when the user is t
Triggers from the description
Arguments
/asyncapi-parser [path/to/asyncapi.yaml]
Original author description
Parses AsyncAPI 3.x specs and generates Drift test cases from them. Use whenever the user wants to generate, write, or scaffold Drift tests from an AsyncAPI spec — especially when the spec contains complex message schemas: oneOf/anyOf/allOf, discriminators, polymorphism, $ref chains, or multiple message variants. Use when the user wants to test async event-driven services (Kafka, SNS, SQS), when they ask to "create tests for a channel", "cover all message variants", "generate test cases from the AsyncAPI spec", or says anything like "each viable combination of messages". Use when the user is t
How it works
- Reference files
- Workflow
SKILL.md preview
---
name: asyncapi-parser
description: >
Parses AsyncAPI 3.x specs and generates Drift test cases from them.
Use whenever the user wants to generate, write, or scaffold Drift tests
from an AsyncAPI spec — especially when the spec contains complex message
schemas: oneOf/anyOf/allOf, discriminators, polymorphism, $ref chains,
or multiple message variants. Use when the user wants to test async
event-driven services (Kafka, SNS, SQS), when they ask to "create tests
for a channel", "cover all message variants", "generate test cases from
the AsyncAPI spec", or says anything like "each viable combination of
messages". Use when the user is trying to understand what payload variants
a message schema produces, or when they paste an AsyncAPI operation and
ask what tests to write.
argument-hint: "[path/to/asyncapi.yaml]"
metadata:
context: fork
agent: general-purpose
---
# AsyncAPI Parser Skill
> **AsyncAPI version:** This skill targets AsyncAPI 3.x (3.0 and 3.1). AsyncAPI 2.x is NOT supported by Drift — if the spec has `asyncapi: "2.x.x"`, tell the user and stop.
## Reference files
- [`references/asyncapi-schema-patterns.md`](references/asyncapi-schema-patterns.md) — how to read and enumerate AsyncAPI 3.x message schemas (oneOf / anyOf / allOf / discriminator / const / correlationId / optional payload fields)
- [`references/asyncapi-drift-mapping.md`](references/asyncapi-drift-mapping.md) — how to map each execution mode and payload variant to Drift YAML, including trigger/probe patterns, `expected` structure per mode, and naming conventions
## Workflow
### 0. Navigate large specifications without loading them wholesale
For a specification over 1,000 lines or 100 KB, do not read or paste the whole
file. Build a line-number index, then inspect only the operation and definitions
that are reachable from it:
```bash
# Establish the document size and top-level section boundaries.
wc -l -c asyncapi.yaml
grep -nE '^(operations|channels|components):' asyncapi.yaml
# List AsyncAPI operation IDs without reading their bodies.
awk '/^operations:/{in_operations=1; next} in_operations && /^[^ ]/{exit} in_operations && /^ [A-Za-z0-9._-]+:$/ {print NR ":" $0}' asyncapi.yaml
```
For a requested operation, locate its line number, then use `sed -n` to read a
bounded range ending at the next operation at the same indentation. Follow the
same pattern for the referenced channel, message, and schema definitions. Never
expand unrelated operations, channels, or every item under `components` merely
to find a match.
Keep a compact fact ledger while resolving references:
| item | source line | refs still to resolve | resolved facts |
| --- | --- | --- | --- |
| operation | | | action, channel, messages, reply |
| channel | | | address |
| message | | | correlation ID, headers, payload ref |
| schema | | | variants, required fields, discriminator |
Process the `refs still to resolve` column as a queue, deduplicating repeated
`$ref` values. Stop when every reachable reference is resolved to primitives or
the schema patterns needed to generate the requested tests. For a request to
cover the entire specification, first index operation IDs, then process one
operation at a time and emit a separate fact ledger entry and test block for
each. This keeps very long documents within context while preserving complete
operation coverage.
### 1. Locate the operation
Extract only what's needed:
```bash
# Find the operation block
grep -n "sendOrderCreated\|receiveInventoryAdjusted" asyncapi.yaml
# Read the operations block and its channel/messages refs
grep -n "^operations:" asyncapi.yaml
```
From the operation block extract:
- `action` — `send` or `receive`
- `channel.$ref` — resolves to a channel name in `channels:`
- `messages[]` — list of `$ref` to message objects
- `reply` block — present only for request-reply interactions
From the channel block:
- `address` — the topic/queue name
From the message block (via `components.messages`):
- `correlationId.location` — where Drift finds the correlation ID
- `headers` schema — header fields
- `payload` schema — the message payload (may be complex: oneOf, anyOf, allOf)
### 2. Resolve $refs recursively
1. Grep for `MessageName:` in `components.messages` to find the definition
2. If the payload itself contains refs, follow those into `components.schemas`
3. Track visited refs. When a schema recursively refers to an active ancestor, preserve the `$ref` back-edge and stop expanding that branch.
4. For external refs such as `./messages.yaml#/Order`, open the referenced file and continue from its JSON Pointer. Report unresolved files or pointers as gaps; never treat them as empty schemas.
5. Stop at primitive types (`string`, `integer`, `boolean`, `array`, `object`, `const`)
`allOf: [$ref: Base, properties: {...}]` is composition — merge all schemas into one full payload. See `references/asyncapi-schema-patterns.md` for all patterns.
### 3. Determine execution mode
Auto-selected by Drift based on `action` + presence of `reply` block:
| operation.action | reply block | mode | Drift role |
|---|---|---|---|
| `send` | absent | `async-observe` | Drift subscribes and captures |
| `receive` | absent | `async-inject` (+ probe) or `async-inject-capture` (+ probe-topic) | Drift publishes |
| `send` | present | `async-request-reply` | Drift publishes request, captures reply |
**Critical:** `action` reflects the **application's** perspective, not Drift's. `send` means your service publishes — Drift subscribes. `receive` means your service consumes — Drift publishes.
### 4. Enumerate payload variants
For **each operation** that has multiple message variants, enumerate structurally distinct schema variants. Aim for minimum tests that maximise schema coverage.
| Pattern | Tests to generate |
|---|---|
| `oneOf` / `anyOf` with N branches in payload | N tests — one per branch |
| `discriminator` with N mapping values | N tests — one per discriminator value |
| `allOf` (composition) | 1 test — merge all schemas into one payload |
| `const` field | 1 test (const is a fixed value — no variants) |
| Optional field cluster in payload | 2 tests: one with all optional fields, one with required only |
| `nullable` payload field | 1 null variant only if it changes behaviour |
See `references/asyncapi-schema-patterns.md` for worked examples.
### 5. Generate Drift test cases
For each variant produce a Drift operation block. See `references/asyncapi-drift-mapping.md` for full patterns. Key conventions:
- Name single-variant operations as `{operationId}_{mode}` — e.g. `SendOrderCreated_Observe`
- Name multi-variant operations as `{operationId}_{variant}` — e.g. `ReceiveInventoryAdjusted_commandType`, `ReceiveInventoryAdjusted_minimal`
- Always include `correlation-id` in `parameters` — it is required for message matching
- Always set `timeout-ms` (default 5000ms; increase for slow services)
- For `async-observe`: include a `trigger` hook — Drift cannot make your service publish
- For `async-request-reply`: do not include a trigger — Drift publishes the request and captures the reply
- For `async-inject`: include a `probe` hook to verify side effects, OR use `probe-topic` for race-condition-free capture
- `expected.headers` + `expected.payload` for message capture modes; `expected` matches probe stdout JSON for `async-inject` mode
- Omitting an `expected.payload` field lets Drift validate it against the AsyncAPI message schema automatically; add explicit field assertions only when asserting specific variant values (e.g. the discriminator property came back correctly)
### Output format
Always produce:
1. **Analysis** — operation name, action, channel address, execution mode, message schema patterns found, how many test variants will be generated and why
2. **Drift operations YAML** — the complete `operations:` block, ready to paste into a test file
3. **Trigger/probe hooks** — shell scripts or Lua function stubs if needed (label as FILL_IN where service-specific)
4. **Gaps** — payload combinations intentionally excluded, with reason
### Example
Given `sendOrderCreated` (action: send, payload has `const: order.created` on `eventType`):
```yaml
operations:
SendOrderCreated_Observe:
target: async-send:sendOrderCreated:orderCreated
description: "Observe the order.created event after trigger fires"
parameters:
correlation-id: send-order-created-001
timeout-ms: 5000
orderId: ORD-100
customerId: CUST-9
trigger:
executable-type: command
value: python3
parameters:
args:
- ./hooks/trigger-send.py
- --correlation-id
- ${parameters.correlation-id}
- --order-id
- ${parameters.orderId}
- --customer-id
- ${parameters.customerId}
timeout-ms: 2000
expected:
headers:
correlation-id: ${parameters.correlation-id}
payload:
eventType: order.created
orderId: ${parameters.orderId}
customerId: ${parameters.customerId}
status: created
```
Files in this package (12)
- SKILL.md 9 KB
- evals/01-send-observe-basic.json 1 KB
- evals/02-receive-inject-payload-variants.json 1 KB
- evals/03-request-reply-operation.json 1 KB
- evals/04-very-long-spec-navigation.json 1 KB
- evals/05-complex-schema-variants.json 1 KB
- evals/fixtures/inventory.asyncapi.yaml 2 KB
- evals/fixtures/order.asyncapi.yaml 1 KB
- evals/fixtures/platform.asyncapi.yaml 3 KB
- evals/fixtures/pricing.asyncapi.yaml 2 KB
- references/asyncapi-drift-mapping.md 9 KB
- references/asyncapi-schema-patterns.md 6 KB
Versions
The database has no other skills named asyncapi-parser.
Database snapshot: 13.11.2026 · package version 4041ffe33727 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100openapi-parser
Parses complex OpenAPI specs and generates Drift test cases from them. Use whenever the user wants to generate, write, or scaffold Drift tests from an OpenAPI spec — especially when the spec contains complex schemas: anyOf/oneOf/allOf, discriminators, polymorphism, inheritance,… - 100asyncapi-generator
Generates an AsyncAPI 3.x YAML spec from a service codebase using ripwire when no spec exists. Invoke this skill whenever the user needs an AsyncAPI spec for an event-driven service that doesn't have one published — phrases like "generate an asyncapi spec from the code",… - 100asyncapi-typescript
Generate TypeScript types, dispatch helpers, AMQP bindings, and framework adapters from an AsyncAPI 3.0 spec via `@ir-kit/asyncapi-typescript`. Use when the user has an event-driven API, message broker schemas, pub/sub workflows, or wants typed publish/consume code for RabbitMQ… - 90agent-event-driven-architect
Specialist subagent: Kafka, RabbitMQ, SQS/SNS, event sourcing, CQRS, and message-driven architecture specialist. Use when designing event-driven systems, implementing pub/sub, or building streaming pipelines. Trigger phrases: Kafka, RabbitMQ, event sourcing, CQRS, message queue,… - 100event-driven-architecture
Kafka, RabbitMQ, SQS/SNS, event sourcing, CQRS, saga patterns, dead letter queues, and idempotency. Use when designing asynchronous systems, implementing message-driven workflows, or building event streaming pipelines. - 90write-tests
WAY 4 — write test cases only, no execution. Use when the user says "write it", "write tests", "generate test cases" — requirements (text or a tracker issue), optional App/Spec/MR or PR → test files + test-plan issue.