peter

# Peter Test Framework Peter is designed to be an extremely lightweight and extensible test framework, with a few test drivers included to accomodate most modes of JavaScript testing. At it's core, Peter was designed with the following intention in mind: > Testing should be as simple as running the file by itself. ## Installation ```bash npm i peter ``` ## Usage To run tests: ```bash # Look in the tests/ directory for test files. npx peter tests/ # Run single test file that's a `.simple` test. npx peter tests/test.simple # Enable verbose output (stdout and stderr from tests will be shown). npx peter -v tests/ ``` Help text: ```console $ npx peter --help peter <testPath> Peter Test Framework Copyright (c) 2020-2023 Distributive Corp., All Rights Reserved. Positionals: testPath The path to a file or directory to run tests from. [string] Options: --help, -h Show help [boolean] --version, -V Show version number [boolean] --concurrency, -j How many tests should be run in parallel. Providing 0 will use 2x # cores (6 on this system). [number] [default: 2] --envFile, -e Path to a ".env" test environment file [string] [default: ".env.test"] --junit, -J Path to write JUnit report file [string] --verbose, -v Enable verbose output (stdout and stderr from tests will be shown). [boolean] [default: false] --quiet, -q Never show stderr from tests [boolean] [default: false] --debug, -d Show debugging information (or set DEBUG=peter) [boolean] [default: false] --timeout, -t Set a timeout in seconds for tests. 0=forever [number] [default: 3600] --repeat, -r Sets the number of times to duplicate the test list [number] [default: 0] --timestamps, -T Show timestamps [boolean] [default: false] -D Dump options to stdout and exit [boolean] [default: false] ``` ## Updates | Version | Date | Description |---------|----------|----------------------- | 2.2.0 | Jun 2021 | Add JUnit XML output | 2.3.0 | Apr 2022 | Add .skip and .failing ## Drivers A peter driver is a module which is responsible for handling files with a specific file extension. The following drivers are included with Peter by default: | Driver Name | File Extension | Description | |-------------|----------------|-------------| | TAP | `.tap` | This driver will run JavaScript files with the `.tap` extension, and expect the standard output of the file to be in [TAP](https://testanything.org/) format. We recommend using [zora](https://www.npmjs.com/package/zora) as a testing library that outputs TAP. | | Simple | `.simple` | This driver will execute JavaScript files with the `.simple` extension, and simply assert that no errors were thrown during execution. Top-level await is supported. Tests with lines matching `// peter-timeout: NUMBER` or `/* peter-timeout: NUMBER */` will have the timeout set to `NUMBER` seconds. | | Bash | `.bash` | This driver will execute Bash scripts as tests, and assert that the exit code of the script is 0. Tests with lines matching `# peter-timeout: NUMBER` will have the timeout set to `NUMBER` seconds. | Note that files with the `.js` extension are ignored by Peter so that utility scripts can be written alongside the test scripts. ## Testing Peter To run the example tests (Peter's self tests), run: ``` ./peter tests ``` ## Debugging Simple Tests If a .simple test fails, you can debug it using ``` ./simple <filename> ``` This file will use [niim](https://www.npmjs.com/package/niim) by default, but `--debugger=<debugger>` can be used to specify a debugger. A `debugger;` call is also automatically added to the start of the `.simple` file being debugged. # About Peter Peter is a Pragmatic, Extensible Test Environment / Runner. It was built based on the observation that developers tend to write a lot of little tests during the course of development, but these little tests tend not to get captured into unit tests. The idea with Peter, in particular the simple tests, is to make it possible for developers to simply take these tests -- often one or two lines of code -- and move them into their `peter` directory, where they become simple pass/fail unit tests. ## Architecture `./peter` is a test runner, which executes tests in random order and in parallel by traversing directories. The test runner discovers the type of test based on the test's file extension. This file extension is then used to select the appropriate test driver, and the test is run. Certain extensions, such as `.js`, are reserved for library code which could be used by multiple tests. If the test filename begins with the mathematical not symbol, `¬`, the sense of the test is inverted (i.e. a pass becomes a fail and vice-versa). ### Simple Simple tests run in NodeJS. If the file throws an uncaught exception or exits with a non-zero exit code, it fails; otherwise it passes. The Simple test driver plumbs in top-level await on Node to make async/await tests easy to run. Individual tests which run directly in NodeJS will run as .simple tests with no changes. Tests written specifically for this test driver can be run individually via `/path/to/simple /path/to/test`. ## Peter A special shout-out to [Peter DeMartini](https://www.npmjs.com/~peterdemartini), who let us have the Peter npm name. Peter is awesome - the end! ## Team Peter was written and is maintained by the team at Distributive. We use it internally to test the [Distributed Computer](https://distributed.computer/). - Wes Garland - Ryan Rossitter - Ryan Saweczko - Andrew Fryer - James McDonald - Parker Rowe - James McDonald - Eddie Roosenmaallen - Bryan Hoang - Nazila Akhavan - Will Pringle - Smeet Chheda