Documentation

The text shown when a file fails to parse or decode. We don't want to show the detailed errors so that users of the test suite can produce the expected output more easily. This is used in .uplc.expected and .budget.expected files.

The text shown when evaluation fails. This is used in .uplc.expected and .budget.expected files.

The default parser to parse UPLC program inputs. FIXME: unlike the flat decoder, this does not detect free variables: they will only be detected if/when we deBruijnify the program.

The input/output UPLC program type.

The format of the test-case input files that the tests should be run against: either the textual `.uplc` representation or the flat-encoded `.flat` representation of the same program. See formatExtension.

The filename extension (without the leading dot) used for a given Format.

The evaluator to be tested.

Directories under which no `.flat` input files are expected and hence shouldn't lead to errors. These test the textual parser's handling of constants, and there are generally no flat equivalents for these tests. This applies to the directory itself and everything below it.

Walk a file tree, making test groups for directories with subdirectories, and test cases for directories without. We expect every test directory to contain a single input file, in the given Format, whose name matches that of the directory. For example, if the Format is UPLC then the directory `modInteger-15` should contain `modInteger-15.uplc`, and that file should contain a textual UPLC program; if the Format is Flat then it should instead contain `modInteger-15.flat`, a flat-encoded UPLC program. The evaluation golden file is named to match: `modInteger-15.uplc.expected` for Textual, or `modInteger-15.flat.expected` for Flat. The budget golden file, however, is always `modInteger-15.budget.expected` regardless of format, since there's no per-format budget convention (the budget only depends on the AST, not on how it was obtained). These golden files will be created by the testing machinery if they aren't already present.

Every test-case directory is expected to have an input file for the requested Format; a missing input file is treated as an error, except under the directories listed in dirsWithNoFlatFiles, where (in Flat mode only) no `.flat` files is expected and the directory is skipped instead (for example `.flat` files don't make sense for the tests under `test-casesuplcevaluationbuiltinparser`, which test the handling of constants by the textual parser).

Check whether some text looks like it's meant to be a UPLC program, ie, whether it begins with `(program` once whitespace and comments (which may appear before the `(` and/or between the `(` and program, as `--` line comments or `{- -}` block comments -- possibly nested, matching the real lexer's whitespace parser in PlutusCore.Parser.ParserCommon -- are ignored).

Turn the expected file content in text to a UplcProg unless the expected result is a parse or evaluation error. We use the same shape-based check as getInputProg (looksLikeUplcProgram) to decide whether the content represents a program at all, rather than just trying to parse it and seeing whether that fails: this way, things like the literal `"parse error"` and `"evaluation failure"` markers are recognised as failures without needing to attempt (and fail) a real parse.

Decode the content of a `.flat.expected` golden file. A `.flat.expected` file records either a successful evaluation result (as flat-encoded bytes) or a failure (as the UTF8-encoded text of shownParseError or shownEvaluationFailure) -- exactly mirroring the `.uplc.expected` convention (see expectedToProg), rather than the old convention of an empty file standing in for "some failure, reason unspecified". We check for the text markers first (a valid flat encoding could coincidentally also be valid UTF8, but it will essentially never happen to be the exact text of one of the two markers).

If the content is neither a recognised failure marker nor a valid flat encoding (for example because the golden file is empty, using the old convention, or has been corrupted), we don't fail outright: instead we return Left with the flat decoder's error text as the "expected" reason. This will essentially never match a real tested value (which is always either a real program or exactly shownParseError/shownEvaluationFailure), so it surfaces as an ordinary golden-mismatch test failure -- visible on a normal run, and fixable with `--accept` like any other outdated golden file (which is how the old empty-file goldens get migrated to the new convention), rather than a special-cased crash.

Obtain the expected UplcProg from a golden `.expected` file in the given Format: parsed as text for Textual (via expectedToProg), or decoded via decodeFlatExpected for Flat.

Obtain the input UplcProg from a test-case input file in the given Format, either by parsing it (for textual) or by flat-decoding it (for Flat). Rather than relying on the parser or decoder itself to fail, we check directly whether the file looks like it's even meant to contain a program: a `.uplc` file is expected to begin with `(program` (once any leading whitespace and comments are ignored: see looksLikeUplcProgram), and a `.flat` file is expected to be non-empty. If a file doesn't meet this expectation, we treat it as shownParseError without attempting to parse or decode it. Otherwise, we go ahead and parse/decode it to get the actual program (this may still fail, for example if the program contains an ill-formed constant).

Get the tested value from a test-case input file in the given Format. The tested value is either the shown parse error or evaluation error, or a res.

The comparison function used for the golden test. This function checks alpha-equivalence of programs when the output is a program. Both Textual and Flat golden values now record the failure reason precisely (see decodeFlatExpected), so in both cases we require it to match.

Update the golden file with the tested value, in the given Format: as text for Textual (unchanged from before), or, for Flat, as flat-encoded bytes on success or the UTF8-encoded failure-reason text on failure (see decodeFlatExpected). TODO abstract out for other tests.

A golden test that is never actually run: it exists only so that it can be passed to parseOptions to make tasty register the Golden test provider's own options (`--accept`, `--no-create`, `--size-cutoff`, `--delete-output`) before the real test tree (which needs the parsed `--format` option to be built in the first place) exists. See the comment in runUplcEvalTests.

Run the UPLC evaluation tests given an evaluator that evaluates UPLC programs. By default the tests are run against the textual `.uplc` test-case files, but passing `--format=flat` on the command line makes them run against the flat-encoded `.flat` files instead (see Format).

Turn a Program using de Bruijn-indexed variables (as decoded from a `.flat` file) into the Name-based representation used elsewhere in this module, so that it can be compared with a program obtained by parsing a textual `.uplc` file.

Decode a flat-encoded UPLC program. We use the UnrestrictedProgram wrapper so that the decoding doesn't reject programs on the grounds of using builtins or term constructs which are unavailable in the version declared by the program: we just want to know whether the bytes decode to the same AST as the textual program that they're supposed to correspond to, not whether they're a valid on-chain script.

Encode a UplcProg as flat bytes: the inverse of decodeFlatProg. Converts the program's names to de Bruijn indices first (that's the representation flat actually encodes), then encodes it via the same UnrestrictedProgram wrapper decodeFlatProg uses, for the same reason (avoiding rejecting programs on the grounds of builtins/term constructs unavailable in the declared version). Used to write `.flat.expected` golden files when accepting a Flat-format test result.