Test Coverage Analysis: JSON Converters and Utility Code

[SeanTAllen]

What's Currently Tested (17 tests)

• Pagination link extraction — 5 example tests covering empty, invalid, first/last/middle pages
• QueryParams encoding — 9 example tests + 3 property-based tests

The Big Gap: JSON Converters (24 primitives, 0 tests)

Every model has a *JsonConverter primitive — a pure function that takes JsonNav and returns a model object. These are the most valuable testing targets because:

1. They're pure functions — no network, no actors, no SSL needed
2. They contain real logic — nullable field handling, nested object parsing, array iteration, optional sub-objects, default values
3. They're where bugs are most likely to hide — wrong field name, missing null check, incorrect nesting

The converters range from trivial (GitPersonJsonConverter: 2 fields) to complex (RepositoryJsonConverter: ~70 fields with nested objects, nullable fields, and optional sub-objects; GistJsonConverter: iterates a JSON object instead of array, has a defaulting comments_enabled field).

Testing Approaches for Converters

Example-based: Construct a JsonObject with the right keys/types, wrap it in JsonNav, call the converter, assert field values match. A minimal test and a test with nullable fields set to null would catch most bugs.

Property-based (higher value):

1. "Valid JSON always succeeds" — generate well-formed JSON matching the schema; converter should never error
2. "Missing required field always fails" — remove one required field from valid JSON; should error
3. "Field values are preserved" — generate valid JSON, convert, check model fields match input values. This is the strongest — catches copy-paste errors where the wrong key is read for a field
4. "Nullable fields accept both string and null" — for every nullable field, test both variants

Other Untested Code Worth Covering

Code	File	Why
JsonNavUtil.string_or_none	json_nav_util.pony	3 code paths (string, null, error) — zero coverage
JsonTypeString	request/json.pony	7 match arms for different JSON types — zero coverage
IssueCommentsURL	issue_comment.pony	Pure URL builder using URI template expansion
GistFile optional fields	gist_file.pony	content/encoding/truncated are absent in list responses but present in detail — both shapes should be tested
Gist.comments_enabled default	gist.pony	Defaults to true when missing — subtle behavior
Gist files-as-object parsing	gist.pony	Structurally different from all other converters (iterates object pairs, not array)

Prioritized Recommendations

1. Start with the simplest converters — GitPersonJsonConverter, LicenseJsonConverter, CommitFileJsonConverter, GistChangeStatusJsonConverter. These establish the test pattern (how to construct JsonNav in tests) with low complexity.

2. Then tackle converters with nullable/optional fields — LabelJsonConverter, IssuePullRequestJsonConverter, AssetJsonConverter, GistFileJsonConverter. These exercise string_or_none and try/else None paths.

3. Then converters with nested objects — GitCommitJsonConverter (nests GitPerson), CommitJsonConverter (nests GitCommit + CommitFile array), IssueJsonConverter (nests User + Label array + optional IssuePullRequest).

4. Then the complex ones — RepositoryJsonConverter (~70 fields), GistJsonConverter (object iteration, defaults).

5. Add JsonNavUtil and JsonTypeString tests alongside the converter work, since converters depend on them.

Property-based tests shine especially for the complex converters where manually enumerating all field combinations is impractical. The "field values are preserved" property is the single most valuable test you could write — it catches the most common bug class (reading the wrong JSON key).

[SeanTAllen]

Item 1 complete — PR #94 merged.

Added 8 property-based tests for the 4 simplest converters: GitPersonJsonConverter, LicenseJsonConverter, CommitFileJsonConverter, GistChangeStatusJsonConverter. Two tests each (preserves-values + missing-field). All counterfactual-verified.

[SeanTAllen]

Item 2 complete — PR #95 merged.

Added 9 property-based tests for 4 converters with nullable/optional fields: LabelJsonConverter, IssuePullRequestJsonConverter, AssetJsonConverter, GistFileJsonConverter. Each gets preserves-values (with Bool generator for nullable field null/non-null) and missing-required-field tests. GistFile gets an additional absent-optional-fields test. All counterfactual-verified.

[SeanTAllen]

Item 3 complete — PR #96 opened.

Added 7 property-based tests for 3 converters with nested objects: GitCommitJsonConverter, CommitJsonConverter, IssueJsonConverter. Each gets preserves-values and missing-field tests. Issue also gets an absent-pull-request test verifying optional field handling. 5 reusable JSON builder helpers (_TestGitPersonJson, _TestCommitFileJson, _TestGitCommitJson, _TestLabelJson, _TestIssuePullRequestJson) compose to build valid nested structures. All counterfactual-verified.

[SeanTAllen]

Items 4 and 5 complete

PR #97 covers the two remaining converter categories and the utility functions:

• Item 4 (complex converters): RepositoryJsonConverter (69 required fields, 4 nullable strings via bitmask, 4 optional nested values) and GistJsonConverter (object iteration for files, comments_enabled default). Three test classes each: preserves-values, missing-field, absent-optional.
• Item 5 (utility functions): JsonNavUtil.string_or_none (string/null/error paths) and JsonTypeString (all 8 match arms). Five test classes total.

That wraps up the testing plan. All five items from this analysis now have PRs: #94 (simplest converters), #95 (nullable fields), #96 (nested objects), #97 (complex converters + utilities).