Migrate typetests to TSTyche by benchristel · Pull Request #3468 · Khan/perseus

benchristel · 2026-04-08T21:54:05Z

Pursuant to ADR #923, we are adopting TSTyche for type testing in TypeScript code!

Test plan:

pnpm tstyche

CI checks should pass.

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

github-actions · 2026-04-08T21:55:16Z

🗄️ Schema Change: No Changes ✅

github-actions · 2026-04-08T21:55:32Z

npm Snapshot: Published

Good news!! We've packaged up the latest commit from this PR (2c8ade5) and published it to npm. You
can install it using the tag PR3468.

Example:

pnpm add @khanacademy/perseus@PR3468

If you are working in Khan Academy's frontend, you can run the below command.

./dev/tools/bump_perseus_version.ts -t PR3468

If you are working in Khan Academy's webapp, you can run the below command.

./dev/tools/bump_perseus_version.js -t PR3468

github-actions · 2026-04-08T21:55:36Z

🛠️ Item Splitting: Changes Detected ⚠️

Usually this means you need to update the Go parser
that Content Platform maintains!!!
Follow these steps on how to release.
See this list of post-mortems for more information.

This PR contains critical changes to Perseus that affect published data.
Please review the changes and note that you may need to
coordinate deployment of these changes with other teams
at Khan Academy, especially with #cp-eng to publish a
content update.

diff --unified /home/runner/work/_temp/branch-compare/base/index.item-splitting.js /home/runner/work/_temp/branch-compare/pr/index.item-splitting.js
--- /home/runner/work/_temp/branch-compare/base/index.item-splitting.js	2026-04-09 23:17:53.420611453 +0000
+++ /home/runner/work/_temp/branch-compare/pr/index.item-splitting.js	2026-04-09 23:17:25.305570851 +0000
@@ -114,7 +114,7 @@
 
 const emptyStringToNull=pipeParsers(constant("")).then(convert(()=>null)).parser;const parseNumberLineWidget=parseWidget(constant("number-line"),object({range:array(number),labelRange:array(nullable(union(number).or(emptyStringToNull).parser)),labelStyle:string,labelTicks:boolean,isTickCtrl:defaulted(boolean,()=>false),isInequality:defaulted(boolean,()=>false),divisionRange:array(number),numDivisions:optional(nullable(number)),snapDivisions:defaulted(number,()=>2),tickStep:optional(nullable(number)),correctRel:defaulted(optional(enumeration("eq","lt","gt","le","ge")),()=>undefined),correctX:defaulted(nullable(number),()=>null),initialX:optional(nullable(number)),showTooltips:optional(boolean),static:defaulted(boolean,()=>false)}));
 
-const parseMathFormat=enumeration("integer","mixed","improper","proper","decimal","percent","pi");const parseSimplify=pipeParsers(union(constant(null)).or(constant(undefined)).or(boolean).or(constant("true")).or(constant("required")).or(constant("correct")).or(constant("enforced")).or(constant("optional")).or(constant("accepted")).parser).then(convert(deprecatedSimplifyValuesToRequired)).parser;function deprecatedSimplifyValuesToRequired(simplify){switch(simplify){case "enforced":case "required":case "optional":return simplify;default:return "required"}}const parseNumericInputWidget=parseWidget(constant("numeric-input"),object({answers:array(object({message:defaulted(string,()=>""),value:optional(nullable(number)),status:string,answerForms:defaulted(optional(array(parseMathFormat)),()=>undefined),strict:defaulted(boolean,()=>false),maxError:optional(nullable(number)),simplify:parseSimplify})),labelText:optional(string),size:string,coefficient:defaulted(boolean,()=>false),rightAlign:optional(boolean),static:defaulted(boolean,()=>false),answerForms:optional(array(object({name:parseMathFormat,simplify:parseSimplify})))}));
+const parseMathFormat=enumeration("integer","mixed","improper","proper","decimal","percent","pi");const parseSimplify=pipeParsers(union(constant(null)).or(constant(undefined)).or(boolean).or(constant("true")).or(constant("required")).or(constant("correct")).or(constant("enforced")).or(constant("optional")).or(constant("accepted")).parser).then(convert(deprecatedSimplifyValuesToRequired)).parser;function deprecatedSimplifyValuesToRequired(simplify){switch(simplify){case "enforced":case "required":case "optional":return simplify;default:return "required"}}const parseNumericInputWidget=parseWidget(constant("numeric-input"),object({answers:array(object({message:defaulted(string,()=>""),value:optional(nullable(number)),status:string,answerForms:defaulted(optional(array(parseMathFormat)),()=>undefined),strict:defaulted(boolean,()=>false),maxError:optional(nullable(number)),simplify:parseSimplify})),labelText:optional(string),size:string,coefficient:defaulted(boolean,()=>false),rightAlign:optional(boolean),static:defaulted(boolean,()=>false)}));
 
 function parseRenderer(rawValue,ctx){return parsePerseusRenderer(rawValue,ctx)}const largeToAuto=(height,ctx)=>{if(height==="large"){return ctx.success("auto")}return ctx.success(height)};const parseOrdererWidget=parseWidget(constant("orderer"),object({options:defaulted(array(parseRenderer),()=>[]),correctOptions:defaulted(array(parseRenderer),()=>[]),otherOptions:defaulted(array(parseRenderer),()=>[]),height:pipeParsers(enumeration("normal","auto","large")).then(largeToAuto).parser,layout:defaulted(enumeration("horizontal","vertical"),()=>"horizontal")}));

github-actions · 2026-04-08T21:55:47Z

Size Change: -34 B (-0.01%)

Total Size: 497 kB

📦 View Changed

Filename	Size	Change
`packages/perseus-core/dist/es/index.item-splitting.js`	11.9 kB	-20 B (-0.17%)
`packages/perseus-core/dist/es/index.js`	25.1 kB	-14 B (-0.06%)

ℹ️ View Unchanged

Filename	Size
`packages/kas/dist/es/index.js`	20.5 kB
`packages/keypad-context/dist/es/index.js`	1 kB
`packages/kmath/dist/es/index.js`	6.36 kB
`packages/math-input/dist/es/index.js`	98.5 kB
`packages/math-input/dist/es/strings.js`	1.61 kB
`packages/perseus-editor/dist/es/index.js`	102 kB
`packages/perseus-linter/dist/es/index.js`	9.3 kB
`packages/perseus-score/dist/es/index.js`	9.7 kB
`packages/perseus-utils/dist/es/index.js`	403 B
`packages/perseus/dist/es/index.js`	194 kB
`packages/perseus/dist/es/strings.js`	8.27 kB
`packages/pure-markdown/dist/es/index.js`	1.39 kB
`packages/simple-markdown/dist/es/index.js`	6.71 kB

_{compressed-size-action}

jeremywiebe

Overall I like how the tests now feel more like .. tests!

jeremywiebe · 2026-04-08T23:30:05Z

.../perseus-core/src/parse-perseus-json/general-purpose-parsers/discriminated-union.typetest.ts

-    // @ts-expect-error - Type '{shape: "extra"}' is not assignable to type 'Figure'
-    parser satisfies Parser<Figure>;
-}
+        expect(parsed).type.toBe<ParseResult<Figure>>();


I notice that the migrations don't do any negative assertions... is that not needed with tstyche or would it be useful to also assert here something like:

expect(parsed).type.not.toBeAssignableTo<ParseResult<string>>();

.toBe() checks the exact shape of a type. In most cases, assignability can be assumed from this point.

Yes, the negative assertions in the old tests were a hack to protect against any being silently inferred. The toBe() matcher fails if one, but not both, of the compared types is any.

jeremywiebe · 2026-04-08T23:34:29Z

.../perseus-core/src/parse-perseus-json/general-purpose-parsers/discriminated-union.typetest.ts

-}
+    it("raises a type error if a variant does not contain the discriminant key", () => {
+        // @ts-expect-error Argument of type 'Parser<OptionalizeProperties<{}>>' is not assignable to parameter of type 'Parser<{ shape: Primitive; }>'
+        discriminatedUnionOn("shape").withBranch("circle", object({}));


This is partly because I haven't worked with these tests much, but it took me a minute to understand that the object({}) was missing a discriminator key. Am I correct in assuming there's no assertion helper that tstyche provides to make this clearer?

Perhaps .not.toBeCallableWith()?

expect(discriminatedUnionOn("shape").withBranch).type.not.toBeCallableWith("circle", object({}));

Is there a way to assert on the error message when using not.toBeCallableWith()?

Nope. That’s a good question! I was thinking on this and drafting an API, but it all looked complicated. The conclusion was that any negated assertion (also those for JavaScript frameworks) do not reveal the exact cause of the error. But we can use positive and negative assertion with only one element changed:

expect(add).toBeCallableWith(1, 2) expect(add).not.toBeCallableWith(1, "2") // all clear why caused the error

Or use @ts-expect-error, as you did already. In a way the message is implementation detail. It might change between TS versions. But sometimes it is useless to see the error as well. TSTyche handles both cases.

jeremywiebe · 2026-04-08T23:54:26Z

packages/perseus-core/src/parse-perseus-json/general-purpose-parsers/test-helpers.ts

+/**
+ * Summons a value of type T out of thin air!
+ *
+ * (Terms and conditions apply. Value will not actually be returned.


jeremywiebe · 2026-04-08T23:55:01Z

packages/perseus-core/src/parse-perseus-json/general-purpose-parsers/union.typetest.ts

+        const alphabet = union(constant("a"))
+            .or(constant("a"))


nit: is this intentional/significant to use constant("a") twice?

Nope, that's accidental. Although, it points out an interesting test case that I missed! Perhaps we should test that union(constant("a")).or(constant("a")).parser parses the same type as constant("a").

jeremywiebe · 2026-04-09T00:08:47Z

packages/perseus-core/src/parse-perseus-json/perseus-parsers/numeric-input-widget.ts

        coefficient: defaulted(boolean, () => false),
        rightAlign: optional(boolean),
        static: defaulted(boolean, () => false),
-        answerForms: optional(


Was this removed because it's no longer valid?

Yes. When I migrated the typetests to TSTyche, I got an error that the parsed type wasn't the same as the data-schema type. This answerForms property, which isn't in data-schema, was the mismatch.

jeremywiebe · 2026-04-09T00:12:15Z

packages/perseus-core/src/parse-perseus-json/general-purpose-parsers/test-helpers.ts

I noticed some tests remove the use of these types. Are they still of use?

They are not! Good catch.

jeremywiebe

Oops, hit the wrong option. Approved!

mrazauskas

Glad to see you choose TSTyche. I am its author.

Overall, the tests look very good. Please ping me if there are any questions in the future.

tstyche.json

mrazauskas · 2026-04-09T07:30:12Z

.../perseus-core/src/parse-perseus-json/general-purpose-parsers/discriminated-union.typetest.ts

-}
+    it("raises a type error if a variant does not contain the discriminant key", () => {
+        // @ts-expect-error Argument of type 'Parser<OptionalizeProperties<{}>>' is not assignable to parameter of type 'Parser<{ shape: Primitive; }>'
+        discriminatedUnionOn("shape").withBranch("circle", object({}));


Perhaps .not.toBeCallableWith()?

expect(discriminatedUnionOn("shape").withBranch).type.not.toBeCallableWith("circle", object({}));

mrazauskas · 2026-04-09T07:40:41Z

.../perseus-core/src/parse-perseus-json/general-purpose-parsers/discriminated-union.typetest.ts

-    // @ts-expect-error - Type '{shape: "extra"}' is not assignable to type 'Figure'
-    parser satisfies Parser<Figure>;
-}
+        expect(parsed).type.toBe<ParseResult<Figure>>();


.toBe() checks the exact shape of a type. In most cases, assignability can be assumed from this point.

packages/perseus-core/src/parse-perseus-json/general-purpose-parsers/object-types.typetest.ts

so we can import {describe, it, expect} from 'tstyche'

…error messages

Co-authored-by: Tom Mrazauskas <[email protected]>

benchristel self-assigned this Apr 8, 2026

benchristel requested review from anakaren-rojas and jeremywiebe April 8, 2026 21:54

benchristel added the olc-5.0.c4fcb label Apr 8, 2026

claude bot reviewed Apr 8, 2026

View reviewed changes

github-actions bot added the item-splitting-change label Apr 8, 2026

jeremywiebe reviewed Apr 9, 2026

View reviewed changes

jeremywiebe approved these changes Apr 9, 2026

View reviewed changes

mrazauskas reviewed Apr 9, 2026

View reviewed changes

packages/perseus-core/src/parse-perseus-json/general-purpose-parsers/object-types.typetest.ts Outdated Show resolved Hide resolved

benchristel force-pushed the benc/tstyche branch from 497b1c5 to cbd310d Compare April 9, 2026 21:29

benchristel added 15 commits April 9, 2026 16:15

[benc/tstyche] Install and configure TSTyche

929c4bf

[benc/tstyche] Run tstyche in CI

abe9261

[benc/tstyche] Use the 'dot' reporter for tstyche

2058716

[benc/tstyche] Convert categorizer widget typetests to tstyche

f2309a1

[benc/tstyche] Add FIXME comment for AI agent

f381566

[benc/tstyche] Convert widget parser tests to tstyche

def5bc9

[benc/tstyche] Migrate categorizer user input typetest to tstyche

261e230

[benc/tstyche] Allow extraneous deps in typetest files

9a534b7

so we can import {describe, it, expect} from 'tstyche'

[benc/tstyche] Add FIXME comment for AI

dd841a0

[benc/tstyche] Fix lint and migrate user input typetests

02a8b79

[benc/tstyche] Don't use the dot reporter for tstyche - it truncates …

039d1ed

…error messages

[benc/tstyche] Add typetests for union parser

178428d

[benc/tstyche] Migrate typetests for pipeParsers to tstyche

0d5eb49

[benc/tstyche] Migrate object-types.typetest.ts to tstyche

0c6c2c6

[benc/tstyche] Migrate enumeration.typetest.ts to tstyche

efd8904

benchristel and others added 11 commits April 9, 2026 16:15

[benc/tstyche] Migrate discriminatedUnionOn typetests to tstyche

f4b3544

[benc/tstyche] Migrate array parser typetests to tstyche

42b80ea

[benc/tstyche] Migrate remaining tests for discriminatedUnionOn

9968261

[benc/tstyche] docs(changeset):

5d7f60a

[benc/tstyche] Fix formatting

c581cc1

[benc/tstyche] Delete unused summonParsedValue() test helper

a103935

[benc/tstyche] Remove unused imports

4430efc

Search for typetest files only in packages/

e1cc296

Co-authored-by: Tom Mrazauskas <[email protected]>

[benc/tstyche] Remove unnecessary summon()s

184fdeb

[benc/tstyche] Add FIXMEs for AI

10116be

[benc/tstyche] Migrate remaining tests

2c8ade5

benchristel force-pushed the benc/tstyche branch from cbd310d to 2c8ade5 Compare April 9, 2026 23:16

benchristel merged commit cedd3f8 into main Apr 10, 2026
12 checks passed

benchristel deleted the benc/tstyche branch April 10, 2026 00:01

Conversation

benchristel commented Apr 8, 2026

Test plan:

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🗄️ Schema Change: No Changes ✅

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

npm Snapshot: Published

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛠️ Item Splitting: Changes Detected ⚠️

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeremywiebe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrazauskas Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeremywiebe left a comment

Choose a reason for hiding this comment

Uh oh!

mrazauskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading

mrazauskas Apr 9, 2026 •

edited

Loading