Menu
Creating/updating corpus tests
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Port a new ballerina/<name> stdlib package from jBallerina to this Go-native interpreter. Use when the user asks to migrate, port, or add a Ballerina standard library module that does not yet exist under `lib/stdlibs/ballerina/`. For filling gaps in an existing stdlib, use `fill-stdlib-gap` instead.
Authoritative format contract for `lib/stdlibs/ballerina/<name>/0.0.1/go1.26/README.md` files. Use when creating or updating any stdlib README, or when auditing an existing one for consistency.
Validate that a ballerina/<name> stdlib's Go public contract does not break the jBallerina public interface. Use when asked to validate, check, or verify a stdlib's public contract against jBallerina, or to review a stdlib PR for public-interface breakage. Produces a summary report at CONTRACT_VALIDATION.md. For porting a new stdlib use `add-stdlib-support`; for filling a gap use `fill-stdlib-gap`.
Fill a gap in an existing ballerina/<name> stdlib — implement a function marked Not Yet Supported, promote a Partially Supported row, or fix a behavioural divergence. Use when the target stdlib already exists under `lib/stdlibs/ballerina/`. For brand-new stdlibs, use `add-stdlib-support`.
Run a given Ballerina source file with jBallerina to compare behaviour against this interpreter
| name | manage-corpus-tests |
| description | Creating/updating corpus tests |
Prefer a corpus .bal test over a Go unit test for everything reachable from Ballerina source. A corpus test runs the full compiler → BIR → interpreter pipeline, so it catches compiler, BIR, and runtime issues — a Go unit test that calls a native helper directly only exercises the runtime. If you cannot write a corpus test for a scenario, that scenario generally cannot happen in the real world.
Corpus tests also count toward native Go coverage: the coverage harness runs ./corpus/... under -coverpkg=./lib/stdlibs/..., so the interpreter executing native code during a corpus run is measured. You do not need Go unit tests to hit a coverage target — drive the native code from .bal instead.
Write a Go unit test only for code that genuinely cannot execute through Ballerina, and keep it minimal:
.bal (passing the wrong type is a compile error — see any *-e.bal @error argument type mismatch). Codebase convention is to not write these guards at all: extern args use x, _ := args[i].(T), not if !ok { return error }.*decimal.Decimal argument).transform.Transformer ErrShortDst branch when x/text sizes its own buffers).When a unit test is justified, say why it is unreachable from Ballerina in a comment so the exception is auditable.
Remove dead code rather than test it. Any Go code that can never execute through Ballerina (an unused helper, a wrong-type error branch the compiler already rejects) is redundant even when a unit test covers it — delete the code and the test. The exemption is only for genuine edge-case / error-handling branches that can be reached with a malformed but well-typed value (bad charset name, malformed date string, out-of-range offset) — cover those from .bal.
@output <expected output>
@error
@panic
--update flag.
go test ./corpus --update.bal are produced by several packages — regenerate across ./ast/... ./semantics/... ./desugar/... ./bir/... ./corpus/ to cover ast/cfg/desugared/bir/integration goldens.--update may rewrite goldens for files you never touched (some stages have non-deterministic ordering, e.g. const/record-field iteration). After updating, git status and revert any change outside the files you added/edited (git checkout <path>) so the changeset stays scoped to your work.bal run $file