tests

Tests

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

Creating a test:

• 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

Updating a test:

• 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

Parser

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

Compiler

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 that exports 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

Features

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.

Coverage

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/.

Other

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