Your SDK’s custom feature is implemented in TypeScript, Go, and Python, and each language has its
own hand-written tests for it. The suites share no cases, so none of them checks a sharp s, and a
book by Botho Strauß gets the shelf label STRAUSS from TypeScript and STRAUß from Go.
What you get
You will end up with one aontu corpus section, its defaults and shared records written once, that the generated TypeScript, Go, and Python suites all run. This is for you if your sdkgen project carries a feature of its own.
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,
and designing 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 | 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 | 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 | 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 | 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 | 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 | 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.
# 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 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:
# Feature behaviour cases, one section per feature.
feature: cost: @"./cost.aontu"
feature: shelfmark: @"./shelfmark.aontu"
Then add the feature and generate, from .sdk/:
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.
node compile.mjs
.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.
node run-case.mjs
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:
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
node others.mjs
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.
node --test corpus.test.mjs
# 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.
node conflict.mjs
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.
node pitfall.mjs
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
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.
Footnotes
-
The merge key has a page of its own 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 does not mention merging at all, so whether
<<works is up to the parser in hand. ↩︎ Back to text -
RFC 8259 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.parseis one of the many. ↩︎ Back to text -
Unicode’s SpecialCasing.txt gives the sharp s three cases on one line: itself in lowercase,
Ssin title case, andSSin uppercase. On this page’s run, Go’sstrings.ToUpperreturnedSTRAUß, and Node’stoUpperCaseand Python’supperreturnedSTRAUSS, the line’s two-letter form. ↩︎ Back to text