Write HTTP API mock files for the kuma-gui mock server under `packages/kuma-http-api/mocks/`. Use whenever the user asks to add or update a mock endpoint, mock a new list/item resource, randomise mock response data with faker, register a new route in `fs.ts`, or extend the `FakeKuma` helpers — even if they don't say the word 'mock'.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Write HTTP API mock files for the kuma-gui mock server under `packages/kuma-http-api/mocks/`. Use whenever the user asks to add or update a mock endpoint, mock a new list/item resource, randomise mock response data with faker, register a new route in `fs.ts`, or extend the `FakeKuma` helpers — even if they don't say the word 'mock'.
metadata
{"author":"Kong","version":1}
You are writing HTTP API mock files for @kumahq/kuma-http-api, the package that ships typed OpenAPI definitions and a mock-data generator consumed by web apps (for example the kuma-gui web app), E2E tests, and the dev preview.
Everything in this skill lives under packages/kuma-http-api/mocks/:
mocks/
├── src/ # one file per endpoint; file path mirrors the URL
├── fs.ts # endpoint → handler routing table
├── Env.ts # typed env-var keys for test overrides
├── FakeKuma.ts # Kuma-specific faker helpers (the `fake.kuma` namespace)
└── index.ts # defines Dependencies, ResponseHandler, pager
Hard constraints
Touch only mocks/. Never edit source code under packages/kuma-http-api/src/ or any other package.
Don't introduce new npm imports inside mock files except types for using in satisfies. The mock "template engine" deliberately exposes everything through the Dependencies argument (fake, pager, env) so that every mock has identical capabilities. If a value needs a reusable generator, add a method to FakeKuma.ts instead of importing a new package.
Every list endpoint paginates through so / query parameters work consistently across the API.
pager
size=
offset=
Every value that varies in reality must be randomised through fake. Hardcoded strings are reserved for literal enum values (type: 'Mesh') and structural constants.
req.params.<x> is string | readonly string[] — always coerce with String(req.params.x) before using it as a string. Template-literal interpolation hides this footgun.
After creating a file, register it in mocks/fs.ts. If you add a new env('KUMA_*', …) key, add it to mocks/Env.ts. If your resource is kri-addressable, also add the kri re-export shim (see below).
Start by finding a sibling
The fastest way to write a correct mock is to find the closest existing resource and copy its shape. Concrete starting points:
Top-level paginated list (global-scoped, no mesh): copy from mocks/src/hostnamegenerators.ts.
Top-level item (kri-addressable, global-scoped, no mesh, supports ?format=kubernetes): copy from mocks/src/meshes/_.ts.
Kuma resource list under a mesh (mesh-scoped): copy from mocks/src/meshes/_/meshtrusts.ts.
Kuma resource item under a mesh (kri-addressable, mesh-scoped, supports ?format=kubernetes): copy from mocks/src/meshes/_/meshtrusts/_.ts.
Sub-resource list under an item (kri-addressable, filterable, nested, supports ?format=kubernetes): copy from mocks/src/meshes/_/meshservices/_/_hostnames.ts.
Copying a sibling absorbs implicit conventions — the kri parsing block, the Transfer-Encoding: chunked randomisation, the ?format=kubernetesmetadata wrapper, the k8s = env('KUMA_ENVIRONMENT', 'universal') === 'kubernetes' switch — that would otherwise have to be re-derived from this document piece by piece. Then change the resource name, type literal, short name, and response type.
File path mirrors the URL
Replace each dynamic path segment with _. _ can be a file (_.ts) or a directory:
headers is usually {}. Use { 'Status-Code': '404' } to return a non-200 status. Many existing mocks also randomly set { 'Transfer-Encoding': 'chunked' } so both response paths are exercised — mirror that if it fits.
body is normally a JSON object. A few stats/metrics endpoints return a plain string instead — that's allowed by the Response type.
#mocks is a subpath import declared in packages/kuma-http-api/package.json that resolves to mocks/index.ts. Always import Dependencies and ResponseHandler from #mocks, never via a relative path.
Typing the response with satisfies
OpenAPI types come from @kumahq/kuma-http-api. Path keys use OpenAPI braces ({mesh}), not Express colons (:mesh) — this is the most common silent footgun.
Always prefer to use a type that lives under paths. Apply the type with satisfies on the returned body so any drift between the mock and the spec becomes a type error:
If the spec hasn't been updated for the new endpoint yet, write the mock without satisfies and leave a TODO — inventing a type that doesn't exist in @kumahq/kuma-http-api would mask future drift.
Working with req
req.url.searchParams is a standard URLSearchParams. req.params.<x> is string | readonly string[] — see the coercion rule in the hard constraints.
The three helpers
fake — Faker with a .kuma namespace
Standard faker modules are all available (fake.word.noun(), fake.number.int(...), fake.datatype.boolean(), fake.helpers.arrayElement(...), fake.internet.url(), fake.lorem.sentence(), fake.date.past(), etc.).
The .kuma namespace contains Kuma-specific helpers: kri identifiers, timespans, labels/tags, policy and resource names, certificates, hostname templates, and more. Before generating any Kuma-shaped value by hand, read packages/kuma-http-api/mocks/FakeKuma.ts — there is almost always a helper for what you need (fake.kuma.timespan(), fake.kuma.kri({…}), fake.kuma.labels({…}), fake.kuma.nanodate(), fake.kuma.policyName(), fake.kuma.shortName('MeshTrust'), …). Add a new method to FakeKuma.ts only if the value is reusable across resources and no existing helper fits.
Both arguments are strings (env values are always strings). Always provide a fake-generated default so the mock is varied out of the box without any setup. Tests, E2E framework specs, and cookie overrides use the same env to constrain values to specific scenarios. Add the new key to mocks/Env.ts.
pageTotal is the number of items for the current page — always use it as the length argument to Array.from. offset + i is a stable global index that survives pagination; prefer it over i for any field that should remain consistent across pages.
Recent Kuma resources are addressable both by their legacy URL (/meshes/:mesh/<resource>/:name) and through a generic /_kri/kri_<short>_:kri endpoint. The same handler serves both. Copy the parsing pattern from a sibling resource — mocks/src/meshes/_/meshtrusts/_.ts is a clean reference.
If your resource isn't kri-addressable (list resource or pre-kri legacy), drop the kri block and use String(req.params.name) directly. As a rule of thumb, if the response includes a top level kri entry, the resource is kri-addressable.
For kri-addressable items, the canonical reference (kri parsing block, ?format=kubernetesmetadata wrapper, randomised chunked encoding) is mocks/src/meshes/_/meshtrusts/_.ts. When in doubt, mirror it exactly and swap the type literal + short name.
kri re-export shim
For every kri-addressable resource, the item handler is also routed under /_kri/kri_<short>_:kri. The wiring lives in two places:
A one-line re-export at mocks/src/_kri/kri_<short>__.ts:
export { default } from'../meshes/_/<resource>/_'
(look at mocks/src/_kri/kri_mtrust__.ts for the exact shape — every kri-addressable resource has one of these.)
An entry in mocks/fs.ts next to the existing // <ResourceName> comment in the kri block:
// MeshFoo'/_kri/kri_mfoo_:kri': _<your-number>,
Forget either and the kri URL form will fall through to the generic /_kri/:kri handler, which returns a stub. Always do both.
Nested resource list with query-param filters
When the UI passes a filter, the mock should reflect it back in the generated rows — otherwise the mock can't be used to test filtered states. Common filters are name and labels. Label filters are prefixed with label. followed by the label key, for example label.kuma.io/zone, label.k8s.kuma.io/namespace or label.kuma.io/listener-zoneingress.
Every Kuma resource also serves a Kubernetes-style response when ?format=kubernetes is set: the apiVersion is added and mesh/name/labels get wrapped inside a metadata object. Don't reinvent this — copy the pattern from mocks/src/meshes/_/meshtrusts/_.ts:
mocks/fs.ts is a flat routing table. Add an import for the new file plus an entry in the exported fs object. The numeric variable names (_1, _42, _628) have no semantic meaning — pick any number that isn't already used in the file (a quick grep is enough). Place the route entry next to related ones and follow the section comments (// meshes, // policies, // resources, // legacy policies, etc.).
Note: fs.ts keys use Express-style colons (:name), even though the OpenAPI types use braces ({name}). This asymmetry is intentional — fs.ts is a URL router, not a spec reference.
Adding env vars
If your mock introduces a new env('KUMA_FOO', ...) key, append it to the keyed type in mocks/Env.ts:
This is what makes env('KUMA_FOO', '...') type-safe — the key is constrained to the union of Env.
Process
Find the closest sibling mock (see "Start by finding a sibling" above) — that's your starting template.
Find the endpoint in packages/kuma-http-api/openapi.yaml — note path, method, params, response schema, and whether the response is paginated.
Decide the file path under mocks/src/ by mirroring the URL with _ for dynamic segments.
Locate the response type in @kumahq/kuma-http-api (paths['/...']['get']['responses']['200']['content']['application/json'] or components['schemas'|'responses']['...']). If the endpoint isn't in the spec yet, skip satisfies and leave a TODO — don't invent a type.
Skim FakeKuma.ts for any helper that already produces the values you need.
Write the mock — randomise every variable field, use pager for lists, env for test overrides, fake.kuma.* for Kuma-shaped values, and satisfies for the response type.
Register the route in mocks/fs.ts.
If kri-addressable, add the kri re-export shim (mocks/src/_kri/kri_<short>__.ts) and the /_kri/kri_<short>_:kri route in fs.ts.
Add new env keys to mocks/Env.ts if you introduced any.
