Authors: Michael Weichert <[email protected]>
Date: Apr 7, 2022
Revision: 1
This plugin integrates automated testing into your workflow via the Jest Testing Framework.
Our Jest plugin exposes the following tasks:
taq init [testsDir]
Initializes the Jest plugin and Jest Testing Framework. Manual invocations of this task are not usually required, as uninitialzed test folders will be initialzed automatically. However, for explicit control, taq init is available as a task for your convenience.
When executed, a .taq/jest.config.js file is created if one doesn't exist, and then too, a jest.config.js is created in testsDir as specified in the positional arguments. testsDir defaults to _jestTestsRootDir if no value was provided.
The .taq/jest.config.js is known as the global jest configuration, and any other jest.config.js files will inherit and override settings defined in the global jest configuration.
E.g, below is an example of a jest.config.js file that would get created in your jestTestsRootDir:
module.exports = {
...require("/.taq/jest.config.js"),
// Set custom configuration here
}
This assures that you can centralize Jest configuration settings that are global to your project, and yet allow granular and individual tweaks for particular use-cases.
taq test [testsDir] [pattern]
The test task is used to execute your automated tests using the Jest testing framework. Running taq test would scan the jestTestsRootDir directory, which defaults to ./tests. The _jestTestsRootDir is a configuration setting specified in your .taq/config.json, and may be changed at any time.
Running taq test without specifying a testsDir will default to working with jestTestsRootDir. A pattern can be specified to pattern-match against filenames in the testsDir to limit what automated tests are executed.
If the jest.config.js file is missing in the specified testsDir, then taq init [testsDir] will be invoked automatically.
Tests can be segmented into partitions, exposed as separate directories underneath the jestTestsRootDir directory. This is sometimes desired to achieve a logical tree-like directory structure for organizational purposes. For instance, a developer may wish to segment their tests for smart contracts from the tests used to test a web application that interacts with the smart contract.
To do this, the developer could create two partitions:
taq test contracts
taq test app
This would create and initialize two partitions for writing Jest automated tests. Assuming your jestTestsRootDir hasn't been customized, then it will default to ./tests and the directory structure will look like the following:
- tests
- tests/contracts
- tests/app
To run all automated tests in the contracts partition, a developer would run:
taq test contracts.
To run all tests, regardless of partition, a developer could run
taq test.
Its expected that other plugins will provide integration with testing frameworks other than Jest. For instance, the LIGO plugin is expected to provide integration with the LIGO Testing Framework which improve the developer workflow for smart contracts authored in one of many syntax available in the LIGO language.
For instance, a developer may wish to organize their tests as such:
- tests
- tests/contracts (using the LIGO testing framework)
- tests/app (using the Jest testing framework)
To do so, a developer would change their jestTestsRootDir to tests/app and ligoTestsRootDir to tests/contracts.
A developer could run their tests written with LIGO with:
taq test --plugin ligo
Likewise, for Jest a developer would run:
taq test --plugin jest
As first mentioned in the State Architecture Design Document, a developer should have the ability to define their own tasks that can integrated into their workflow.
End-developer defined tasks are configurated in .taq/config.json.
This capability offers the ability to define a task which wraps existing ones.
E.g.:
...,
"tasks": {
"test": {
"handler": "taq test --plugin ligo && taq test --plugin ligo"
}
} This would expose a task that would run all tests defined using the LIGO and Jest plugin:
taq run test