Skip to content

test(commons): add golden fixture corpus for LongEncoding - #3146

Open
dpol1 wants to merge 1 commit into
apache:masterfrom
dpol1:feat/3145-longencoding-golden-fixtures
Open

test(commons): add golden fixture corpus for LongEncoding#3146
dpol1 wants to merge 1 commit into
apache:masterfrom
dpol1:feat/3145-longencoding-golden-fixtures

Conversation

@dpol1

@dpol1 dpol1 commented Aug 8, 2026

Copy link
Copy Markdown
Member

Purpose of the PR

LongEncoding encodes ids and sortable keys, so its exact behavior is a compatibility contract, including the intentional overflow wrapping around Long.MIN_VALUE and inputs the decoder accepts but the encoder never produces. Today that contract exists only implicitly in the implementation. This PR pins it in a committed, implementation-independent corpus that any port or refactor can be checked against line by line.

Main Changes

  • LongEncodingGoldenGenerator (test scope): produces the corpus by running the current implementation and recording, for each input, the exact output or the exception class. Deterministic: fixed value sets plus a fixed random seed, duplicate lines dropped.
  • longencoding-golden.txt (test resource): 3940 cases, plain ASCII, tab separated with \uXXXX escapes. Covers full-range round trips including Long.MIN_VALUE/MAX_VALUE, non-canonical decode inputs (00 decodes to MIN while encode produces 010), arbitrary UTF-16 decode input including surrogates, the error taxonomy (IllegalArgumentException vs NumberFormatException vs NPE), and length limits.
  • LongEncodingGoldenTest: two checks. It replays every corpus line against the implementation, and it regenerates the corpus in memory to assert the committed file matches the generator output exactly, so generator and resource cannot drift apart.
  • Both tests registered in UnitTestSuite so commons CI executes them.

Review guide: the review surface is the generator (case selection, ~370 lines), the corpus format documented in the file header, and the two-way check mechanics. The corpus file is generated output verified by testCorpusMatchesGenerator and does not need line-by-line review.

Contract boundaries: six operations (encodeSortable/decodeSortable, encodeB64/decodeB64, encodeSignedB64/decodeSignedB64). Exact output strings and decoded values are contract; the exception class is contract, the exception message deliberately is not. No production code changes.

Verifying these changes

  • Need tests and can be verified as follows:
    • mvn test -pl hugegraph-commons/hugegraph-common -Dtest=UnitTestSuite -DskipCommonsTests=false on JDK 11 (the commons CI toolchain): 345 tests, the only errors are 2 environment NPEs in MachineInfoTest that reproduce identically on a clean master checkout in the same environment.
    • Tamper check: altering one byte of the corpus fails both new tests; regenerating restores green.
    • apache-rat:check, checkstyle:check and git diff --check are clean.

Does this PR potentially affect the following parts?

  • Nope

Documentation Status

Lock down the current encode/decode behavior of LongEncoding as a
compatibility contract: exact outputs across the full value range
including the wrapping arithmetic around Long.MIN_VALUE, accepted
non-canonical inputs, and the exception class for each rejected input.
Exception messages are deliberately not part of the contract.

The corpus is generated by running the current implementation
(LongEncodingGoldenGenerator, deterministic seed) and verified two
ways: LongEncodingGoldenTest replays every line against the current
implementation, and regenerates the corpus in memory to check the
committed file matches the generator, so the two cannot drift apart.
Both tests are registered in UnitTestSuite so commons CI runs them.
@dosubot dosubot Bot added size:XS This PR changes 0-9 lines, ignoring generated files. tests Add or improve test cases labels Aug 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XS This PR changes 0-9 lines, ignoring generated files. tests Add or improve test cases

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant