This directory contains the test cases for AssemblyScript's parser and compiler. A test case consists of:
- A test file that is parsed or compiled (.ts)
- One or multiple automatically generated fixtures generated from the source file
- Run
npm run clean
to make sure that the sources are tested instead of the distribution - Create a new test file (.ts) within the respective directory (see below) that contains your test code
- Follow the instructions below to generate the first fixture(s)
- Make sure the fixture(s) contain exactly what you'd expect
- Run
npm run clean
to make sure that the sources are tested instead of the distribution - Make changes to the respective test file (.ts)
- Follow the instructions below to update the fixture(s)
- Make sure the fixture(s) contain exactly what you'd expect
See also: Contribution guidelines
Directory: tests/parser
The test file is parsed while warnings and errors are recorded and re-serialized to a new source afterwards. The new source with warnings and errors appended as comments is compared to the fixture.
Running all tests:
$> npm run test:parser
Running a specific test only:
$> npm run test:parser -- testNameWithoutTs
To (re-)create all fixtures:
$>npm run test:parser -- --create
To (re-)create a specific fixture only:
$> npm run test:parser -- testNameWithoutTs --create
General directory: tests/compiler
Standard library directory: tests/compiler/std
The source file is parsed and compiled to a module, validated and the resulting module converted to WebAsssembly text format.
The text format output is compared to its fixture and the module interpreted in a WebAssembly VM. To
assert for runtime conditions, the assert
builtin can be used. Note that tree-shaking is enabled
and it might be necessary to export entry points.
Additional fixtures for the optimized module etc. are generated as well but are used for visual confirmation only.
If present, error checks are performed by expecting the exact sequence of substrings provided within
the respective .json
file. Using the stderr
config option will skip instantiating and running
the module.
Optionally, a .js
file of the same name as the test file can be added containing code to run pre
and post instantiation of the module, with the following export signatures:
-
preInstantiate(imports:
object
, exports:object
):void
Can be used to populate imports with functionality required by the test. Note thatexports
is an empty object that will be populated with the actual exports after instantiation. Useful if an import needs to call an export (usually in combination with the--exportStart
flag). -
postInstantiate(instance:
WebAssembly.Instance
):void
Can be used to execute custom test logic once the module is ready. Throwing an error will fail the instantiation test.
Running all tests:
$> npm run test:compiler
Running a specific test only:
$> npm run test:compiler -- testNameWithoutTs
To (re-)create all fixtures:
$> npm run test:compiler -- --create
To (re-)create a specific fixture only:
$> npm run test:compiler -- testNameWithoutTs --create
Tests for experimental features (usually enabled via the --enable
CLI flag) are disabled by default. To enable a feature, set the ASC_FEATURES
environment variable to a comma-separated list of feature names (see features.json
). You can also set ASC_FEATURES="*"
to enable all features.
An optional code coverage report can be generated by running
$> npm install c8
$> npm run coverage
Code coverage runs the tests with c8 using the JS variant of the compiler. It is expected that Wasm-only branches show as untaken. Make sure to enable all (relevant) features. A convenient HTML report is generated to coverage/
.
Tests in other directories are not run automatically and do not need to be updated. There are also:
- tests/allocators contains the memory allocator test suite
- tests/browser checks typical browser usage via asc's API
- tests/tokenizer is a visual test for the tokenizer tokenizing itself