# How to write an SDK feature test corpus in aontu instead of JSON

> Write a custom sdkgen feature's cases once in aontu, with shared defaults and records, and run them in the generated TypeScript, Go, and Python suites.

Source: https://voxgig.com/howto/write-a-feature-corpus-in-aontu

- Audience: api-producer
- Level: advanced
- Languages: typescript, go, python
- Verified: 2026-11-21
- Published: 2026-11-21

## Short answer

In an sdkgen project, write the feature's cases in .sdk/test/feature/<name>.aontu as a basic set, each with name, feature, res, op, and out, and register the file in feature-test-index.aontu. Put shared defaults in a hidden case template and shared records behind $. references. npm run generate compiles the corpus into .sdk/test/test.json, and the generated suite of every target runs it.

---
## You will need

Node 22 or later, an sdkgen project with a feature of its own, and Go and Python if you run those
suites. This page scaffolds one from the five-operation Bookshelf document with `ts`, `go`, and
`py` targets. Its feature, `shelfmark`, labels a book-shaped result as `HERBERT, Dune (1965)` and
records the count and the last label on the client as `_shelfmark`. The case fields come from
[sdkgen's guide to adding a feature](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-feature.md),
and [designing the case shape of a test corpus](/howto/design-the-case-shape-of-a-test-corpus)
covers why cases need ids and sentinels.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Cucumber Gherkin features](https://cucumber.io/docs/gherkin/reference/) | People who do not write code read and write the cases | A step definition in every language for every step, matched to the step's text by code you write | Every reader of the cases is a programmer |
| [Kiota with a mocked request adapter](https://learn.microsoft.com/en-us/openapi/kiota/testing) | Each language's client has its own team and its own unit tests | No feature model and no generated tests, so every suite is written and kept by hand | Several languages must prove one behavior from one file |
| [Plain JSON corpus](https://www.rfc-editor.org/rfc/rfc8259.html) | Every language reads it with its standard library, and nothing compiles it | Each case restates its setup, and a repeated key drops a case without an error | Cases share setup and records, and the file outgrows a screen |
| [sdkgen .aontu corpus](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/add-a-feature.md) | An sdkgen project's own feature must behave alike in every target | A language contributors must learn, a compile step, and assertions only on the client's record and error codes | One target, or a case that needs a function |
| [Swagger Codegen test stubs](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generation-selective/) | A team wants one test file per API class to fill in | A stub per operation in each language, so the same case is written once per language | One set of cases must reach every language |
| [YAML corpus with anchors](https://yaml.org/type/merge.html) | Cases share setup, and contributors already read YAML | The `<<` merge key lets a local key win without a message, and YAML 1.2 omits it | Two cases that disagree must stop the build |

Voxgig maintains sdkgen and aontu. They are this page's subject and one row of six, and their row
names the conditions for picking another.

A plain JSON corpus is the one every language reads without a compile step, and it pays in
repetition: the section on this page spells out the feature list in four cases. YAML anchors
remove the repetition with a merge rule that resolves a clash silently.[^1] Gherkin reads best
and costs a step definition per language. Kiota and Swagger Codegen ship no shared corpus, so each
language team writes its own cases.

## Write the cases with defaults and references

A feature's section is a list under `basic: set`. Each case has a `name`, a `feature` list in
add order, `res` for the responses the scripted transport returns, `op` for the calls to make, and
`out`. The runner compares `out` with the client's `_shelfmark` record as a subset, so a case
states only the fields it is about. `#OP1` stands for an operation the runner picks, because no
case may name an entity that only some SDKs have.

```aontu title=".sdk/test/feature/shelfmark.aontu"
# The shape of one case. Defaults switch the feature on and call the first
# operation once, so a case states only what it is about.
case: hide({
  name: string
  feature: *[ { name: 'shelfmark', active: true } ] | top
  res: [&: { status: integer & min(100) & max(599), body: top }]
  op: *[ { op: '#OP1' } ] | top
  out: { count: integer & min(0), last: string }
})

# Records shared by several cases, referenced with $. paths.
book: hide({
  dune: { id: 'b1', title: 'Dune', author: 'Frank Herbert', published: 1965 }
  paare: { id: 'b2', title: 'Paare, Passanten', author: 'Botho Strauß', published: 1981 }
})

basic: set: [&: $.feature.shelfmark.case]

basic: set: [

  {
    name: 'labels a book-shaped result'
    res: [ { status: 200, body: $.feature.shelfmark.book.dune } ]
    out: { count: 1, last: 'HERBERT, Dune (1965)' }
  }

  {
    name: 'capitalizes a sharp s as SS'
    res: [ { status: 200, body: $.feature.shelfmark.book.paare } ]
    out: { count: 1, last: 'STRAUSS, Paare, Passanten (1981)' }
  }
```

Four [aontu](https://aontu.dev/) constructs do the work. `hide()` evaluates a value and keeps it out
of the output. `*[ ... ] | top` is a default, which a case overrides by writing its own list, as
the fourth case does with two calls. `[&: ...]` applies the template to every element, and a `$.`
path starts at the root of the compiled corpus, where the index puts this file under
`feature.shelfmark`.

The template types each field as well. A status outside 100 to 599, a status written as a string,
or a negative count stops the compile, before any runner sees the case.

## Register the section and compile it

The scaffold ships the index with a `cost` section. The second line registers this one:

```aontu title=".sdk/test/feature/feature-test-index.aontu"
# Feature behaviour cases, one section per feature.
feature: cost: @"./cost.aontu"
feature: shelfmark: @"./shelfmark.aontu"
```

Then add the feature and generate, from `.sdk/`:

```bash
npx voxgig-sdkgen feature add shelfmark
npm run generate
```

`npm run generate` ends with `voxgig-model test/test.aontu`, which writes `.sdk/test/test.json`,
and `npm run test-model` runs that step alone. `compile.mjs` compiles the same source with the
`aontu` package and compares it with the section the generator wrote.

```bash
node compile.mjs
```

```text output
.sdk/test/feature/shelfmark.aontu, compiled with aontu 0.76.3
  cases: 4
    labels a book-shaped result: feature shelfmark, 1 response(s), 1 call(s)
    capitalizes a sharp s as SS: feature shelfmark, 1 response(s), 1 call(s)
    ignores a result without an author: feature shelfmark, 1 response(s), 1 call(s)
    keeps the label of the last book-shaped result: feature shelfmark, 2 response(s), 2 call(s)
  keys of the section: basic
  same as generated/shelfmark.json: true
  written once in the source, spelled out in the JSON:
    the default feature list, shelfmark active: 4 cases
    the default call, one #OP1: 3 cases
    the Dune record: 2 responses
    the Paare, Passanten record: 2 responses
```

The section's only key is `basic`, because `case` and `book` stayed in the source. The JSON a runner
reads repeats each of those values, which is the text a hand-written JSON corpus would carry.

## Run the cases in every target's generated suite

Each target's generated suite reads `.sdk/test/test.json` directly: `ts/test/feature/Corpus.test.ts`,
`go/test/feature_corpus_test.go`, and `py/test/test_feature_corpus.py`. Each one takes its section
names from the corpus, skips a section whose feature the SDK lacks, as it skips `cost` here, and
prints how many cases ran. `run-case.mjs` runs the cases against the committed TypeScript build as
the runner does, with `#OP1` as `book.list`, the first operation the runner can call without
arguments.

```bash
node run-case.mjs
```

```text output
TypeScript SDK, run here:
  match  labels a book-shaped result
  match  capitalizes a sharp s as SS
         want "STRAUSS, Paare, Passanten (1981)"
         got  "STRAUSS, Paare, Passanten (1981)"
  match  ignores a result without an author
  match  keeps the label of the last book-shaped result
generated suites, run by generate.sh:
  ts  ran 4 of 4 cases, passed: true
  go  ran 4 of 4 cases, passed: true
  py  ran 4 of 4 cases, passed: true
```

The TypeScript runner compares a stated field with `deepStrictEqual`, Python with `==`, and Go by
formatting both sides with `%v`, so a label is compared byte for byte in all three. Numbers are
compared less strictly in Go and Python, which allow a difference of `1e-9`, than in TypeScript,
which allows none.

## Give Kiota and Swagger Codegen clients the same cases

Neither generator has a feature model or a shared corpus, so each language's cases and runner are
yours to write. Kiota 1.39.0 wrote no test files here, and the options of `kiota generate` include none for tests. Its testing page mocks the request adapter, the layer
that holds a Kiota client's HTTP transport, in a C# sample. The substitute is a
JSON corpus and one runner per language that serves each case's `res` from that mock.

Swagger Codegen writes test stubs, here for Python and TypeScript but not Go, unless
`-DapiTests=false` and `-DmodelTests=false` turn them off, as its selective generation page documents. Its Python stub for this document:

```python title="generated/others/swagger/python/test/test_default_api.py"
class TestDefaultApi(unittest.TestCase):
    """DefaultApi unit test stubs"""

    def setUp(self):
        self.api = DefaultApi()  # noqa: E501

    def tearDown(self):
        pass

    def test_create_book(self):
        """Test case for create_book

        """
        pass
```

```bash
node others.mjs
```

```text output
Kiota 1.39.0
  go                 5 files, tests: none
  python             5 files, tests: none
  typescript         5 files, tests: none
Swagger Codegen 3.0.85
  go                14 files, tests: none
  python            23 files, tests: test/__init__.py, test/test_book.py, test/test_default_api.py
  typescript-fetch   9 files, tests: api_test.spec.ts
hand-added lines in test_default_api.py after a second generate: 1
```

A second generate left a line added to the Python stub in place, so a filled-in stub survived
that run. The Go client got no stub, so each case is still written once per language.

## Check it worked

The tests compile the source and compare it with the generator's section. They run every case
against the TypeScript SDK, change one byte of an expected label and expect a failure, and read
the three recorded suite runs.

```bash
node --test corpus.test.mjs
```

```text output
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The compile stops with `scalar_value` at `basic.set.0.name`. A second list under `basic: set`
unifies with the first element by element instead of appending, so two cases at index 0
contradict each other. Keep one list per section; the `[&: ...]` template is the second statement
that merges cleanly.

```bash
node conflict.mjs
```

```text output
a scripted status written as '200'
  error constraint at $.feature.shelfmark.basic.set.1.res.0.status
  sites: shelfmark-typo.aontu:33:22 and shelfmark-typo.aontu:10:32
a second list of cases in broken/two-lists.aontu
  error scalar_value at $.feature.shelfmark.basic.set.0.name
  sites: shelfmark.aontu:26:11 and two-lists.aontu:5:11
the same two lists in broken/two-lists.json
  JSON.parse kept 1 case: labels a paperback
```

Both errors name the two sites that disagree. The JSON form of the second mistake, a repeated
`basic` key, parses, and `JSON.parse` keeps the last value.[^2]

A case you added is gone after the next generate, because it went into `.sdk/test/test.json`,
which `npm run generate` writes again from the `.aontu` source. One language fails a case the others pass when an
implementation differs: the Go feature first used `strings.ToUpper`, which left the sharp s
unchanged.[^3] The fix belongs in `.sdk/tm/go/feature/`, the copy every generate writes
`go/feature/` from.

```bash
node pitfall.mjs
```

```text output
a case added to .sdk/test/test.json by hand
  cases before the hand edit: 4
  cases after the hand edit: 5
  cases after npm run generate: 4
the Go feature with strings.ToUpper, against the same corpus
  capitalizes a sharp s as SS: _shelfmark.last: got STRAUß, Paare, Passanten (1981), want STRAUSS, Paare, Passanten (1981)
  feature.shelfmark: ran 4 of 4 case(s) against 2 operation(s)
  go test exit 1
```

## When not to do this

Do not write an sdkgen corpus section for a feature that only one target implements. A test file
in that language is shorter, and it needs no compile step and no second notation.

Do not put a case in the corpus when its subject needs a function, such as a callback option.
Everything in a case is data, and sdkgen's own guide sends those subjects to tests in
each language.

Kiota with tests per language is the better fit when every language's client has its own team
and its own release, because a mocked request adapter needs no shared file. Swagger Codegen's stubs
suit a team that wants one test per operation laid out for it to fill in.

Do not choose aontu for a corpus that people outside the SDK team edit. Plain JSON costs
repetition, and every contributor already reads it.

## Related how-tos

- [Design the case shape of a language-neutral test corpus](/howto/design-the-case-shape-of-a-test-corpus)

- [Add a custom feature that survives SDK regeneration](/howto/add-a-custom-feature-to-a-generated-sdk)

- [Choose between a shared test corpus and Pact contracts](/howto/choose-between-a-shared-corpus-and-pact-contracts)

- [Run an in-memory mock of your API inside SDK tests](/howto/run-an-in-memory-mock-inside-sdk-tests)

## Last verified

Verified 2026-11-21 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3,
`@voxgig/apidef` 8.32.4, `@voxgig/model` 12.0.2, aontu 0.76.3, Kiota 1.39.0, and Swagger Codegen
3.0.85. `generate.sh` ran once, with network access. It scaffolded and generated the SDK and ran the
generated TypeScript, Go, and Python suites, on Go 1.24.7 and Python 3.13.18 with pytest 9.1.1.
It also ran Kiota and Swagger Codegen on the same document. Its output is committed under `generated/`.
The gate re-runs the commands on this page, which compile the corpus, drive the committed
TypeScript build, and read those records. The Gherkin and YAML rows come from their documentation.

[^1]: The merge key has a [page of its own](https://yaml.org/type/merge.html) on yaml.org, a
"Working Draft 2005-01-18" for YAML 1.1, which inserts each merged key "unless the key already
exists" in the mapping. The [YAML 1.2.2 specification](https://yaml.org/spec/1.2.2/) does not
mention merging at all, so whether `<<` works is up to the parser in hand.

[^2]: [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html#section-4) says the names within
an object SHOULD be unique. It also records what happens when they are not: the behavior of
software that receives such an object is unpredictable, and many implementations report the last
name and value pair only. `JSON.parse` is one of the many.

[^3]: Unicode's [SpecialCasing.txt](https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt)
gives the sharp s three cases on one line: itself in lowercase, `Ss` in title case, and `SS` in
uppercase. On this page's run, Go's [`strings.ToUpper`](https://pkg.go.dev/strings#ToUpper)
returned `STRAUß`, and Node's `toUpperCase` and Python's `upper` returned `STRAUSS`, the line's
two-letter form.