Module test

Defines a test file format for stack graph resolution.

Assertions

Test files are source files in the language under test with assertions added in comments. Assertions indicate the position of a reference or definition with a carrot ^ in the source, and specify comma separated expected values.

An example test for Python might be defined in test.py and look as follows:

foo = 42
# ^ defines: foo
print(foo, bar)
#     ^ refers: foo
#     ^ defined: 1
#          ^ refers: bar
#          ^ defined:

Consecutive lines with assertions all apply to the last source line without an assertion. In the example, both assertions refer to positions on line 3.

The following assertions are supported:

• defined: takes a comma-separated list of line numbers, and expects a reference at this position to resolves to definitions on those lines.
• defines: takes a comma-separated list of names, and expects definitions at this position with the given names.
• refers: takes a comma-separated list of names, and expects references at this position with the given names.

Fragments for multi-file testing

Test files may also consist of multiple fragments, which are treated as separate files in the stack graph. An example test that simulates two different Python files:

# --- path: one.py ---
x = 42
y = -1
# --- path: one.py ---
print(x, y)
#     ^ defined: 2
#        ^ defined: 3

Note that the line numbers still refer to lines in the complete test file, and are not relative to a fragment.

Any content before the first fragment header of the file is ignored, and will not be part of the test.

Structs

Test

A stack graph test

TestFragment

A fragment from a stack graph test

TestResult

Result of running a stack graph test.

Enums

TestError

An error that can occur while parsing tests

TestFailure

Description of test failures.