How-to › Maintain libraries across languages

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.

Audience
API producer
Level
advanced
Topic
Test once, run in every language
Languages
TypeScript, Go and Python
Verified

Read first: Design the case shape of a language-neutral test corpus

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Cucumber Gherkin featuresPeople who do not write code read and write the casesA step definition in every language for every step, matched to the step’s text by code you writeEvery reader of the cases is a programmer
Kiota with a mocked request adapterEach language’s client has its own team and its own unit testsNo feature model and no generated tests, so every suite is written and kept by handSeveral languages must prove one behavior from one file
Plain JSON corpusEvery language reads it with its standard library, and nothing compiles itEach case restates its setup, and a repeated key drops a case without an errorCases share setup and records, and the file outgrows a screen
sdkgen .aontu corpusAn sdkgen project’s own feature must behave alike in every targetA language contributors must learn, a compile step, and assertions only on the client’s record and error codesOne target, or a case that needs a function
Swagger Codegen test stubsA team wants one test file per API class to fill inA stub per operation in each language, so the same case is written once per languageOne set of cases must reach every language
YAML corpus with anchorsCases share setup, and contributors already read YAMLThe << merge key lets a local key win without a message, and YAML 1.2 omits itTwo 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.

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

  1. 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

  2. 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.parse is one of the many. ↩︎ Back to text

  3. Unicode’s 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 returned STRAUß, and Node’s toUpperCase and Python’s upper returned STRAUSS, the line’s two-letter form. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.