https://github.com/ahwayakchih/pete

PeTe: Performance Tester (benchmark runner) for Bun and Node.js
https://github.com/ahwayakchih/pete

benchmarking nodejs performance-testing testing

Last synced: 6 months ago
JSON representation

PeTe: Performance Tester (benchmark runner) for Bun and Node.js

• Host: GitHub
• URL: https://github.com/ahwayakchih/pete
• Owner: ahwayakchih
• License: isc
• Created: 2019-03-09T14:21:46.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2025-07-27T14:49:31.000Z (11 months ago)
• Last Synced: 2025-08-28T05:36:15.999Z (10 months ago)
• Topics: benchmarking, nodejs, performance-testing, testing
• Language: JavaScript
• Homepage: https://ahwayakchih.github.io/pete/
• Size: 195 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
PeTe

=====

PeTe is a performance tester, a benchmark runner for JavaScript functions (or whole scripts).

Compatible with both [Node.js](https://nodejs.org/) and [Bun](https://bun.sh/).

It's primary goal is to make benchmarking as easy as possible. So, instead of creating its own specific (and overly complicated) API, it offers three simple functions that you might find incredibly similar to those you already know from simpler test modules (like [`tape`](https://github.com/ljharb/tape) or Node's built-in test-runner):

- `test`: runs a function in two "phases" ("warmup" and "regular"),

- `skip`: does not run the function at all, just marks result as skipped,

- `todo`: runs function without "warmup" phase, marks result as "todo" and does not stop tests if it errors out.

Each of them accepts the same number and type of parameters. They differ only by how the results are interpreted.

- `name` of a test is optional, if not provided, PeTe will use benchmarked function's "id" (filename, line number),

- `fn` is a required function that is to be benchmarked,

- `options` is an optional object that may contain any of the [supported options](lib/RunOptions.js),

- `cb` is an optional function to call after benchmarking of the `fn` function ends.

## Installation

To install PeTe, as with most of the other Node.js modules, use following command line:

```sh

npm install @ahwayakchih/pete

```

or install it globally:

```sh

npm install -g @ahwayakchih/pete

```

## Usage (API)

The simplest possible way to run a test is:

```js

const test = require('pete/test');

test(myCustomFunction);

/**

 * This is the function that's being tested above.

 */

function myCustomFunction () {

  return "done";

}

```

Of course you can pass any type of function to it. PeTe tries to automatically recognize if that function is synchronous (like in example above), "callback"-style (last of its params is called either: "cb", "callback", "done" or "next"), `async` or returns a Promise. If a string is passed in place of a function, PeTe will try to run forked process assuming that the string is a path to a script file.

If that fails for some reason, you can always enforce your choice by passing additional `runType` option:

```js

const test = require('pete/test');

test(myCustomFunction, {

  // @see: lib/runs/auto.js for current list of supported/"built-in" `runTypes`

  runType: 'sync'

});

function myCustomFunction () {

  return "done";

}

```

You can even create your own "runner" module. PeTe will first try its own runners, and if none is found with specified name, it will try to `require` module with that name (which means, that module should export a single function). Check how [`pete/lib/runs/skip`](lib/runs/skip.js) and other runners are implemented.

## Usage (CLI)

If you installed PeTe globally, or you are trying to use it from your project's `package.json` script(s), you should be able to use it like this:

```sh

pete test-file.js

```

It supports following options:

- *-c, --maxCpuTime*      : limit total time (in milliseconds) that target test can take when run multiple times

- *-r, --maxRealTime*     : limit total time (in milliseconds) that a single test run can take

- *-s, --maxSamples*      : limit how many times target function should be called when tested

- *-w, --maxWarmup*       : same as `samples`, only for "warmup" phase of test run

- *-p, --percentile*      : specify which percentiles you want reported

- *-o, --output, --report*: specify reporter(s)

- *-b, --bail*            : set to `false` (or use `-no` prefix: `--no-bail`) to continue to the next test, when one errors out

- *-j, --just, --only*    : specify ID of the test you want to be run as the only one from the file(s)

- *-a, --arg*             : optionally specify one or more arguments to be passed to tested function(s)

You can also pass a JSON file with previous report data, for example to "convert" it to another supported format:

```sh

pete examples/index.js -o json?out=reports/examples.json

pete reports/examples.json -o tap

```

Of course, any test file that uses PeTe, can be run directly and supports same CLI options.

For example, to run test for maximum of 3 seconds and output results in [`TAP`](https://testanything.org/) format:

```sh

node examples/example1.js --maxRealTime 3000 --report tap

```

Or same situation but using Bun:

```sh

bun --expose-gc examples/example1.js --maxRealTime 3000 --report tap

```

To get results in a format that's a bit more readable for a common human, use `mico` reporter:

```sh

node examples/example1.js --maxRealTime 3000 --report mico

```

That will output something similar to:

```txt

   s name                         p99         max           ops           samples      *p99   

  --------------------------------------------------------------------------------------------

   ✔ sync1                     🕛  121ns    97,279ns   ~23,053,627/s   |11,252,924|   × 1.00  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜶘𜴦🮔

   ✔ callback3                 🕐  130ns   122,623ns   ~21,624,682/s   |12,667,593|   × 1.07  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜶘𜶘𜴦🮔

   ✔ generator1                🕐  140ns    32,351ns   ~16,652,797/s   | 9,625,101|   × 1.16  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜶘𜴦🮔🮔

   ✔ async1                    🕗  220ns   166,015ns   ~ 7,103,987/s   | 7,584,502|   × 1.82  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶘𜶫🮔🮔

   ✗ callback1ToDo             Error: Intentional Test Error

  🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔

   ✗ callback2ToDoException    Error: Intentional Test Exception

  🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔

```

To keep the difference column ("\*p99"), but without horizontal bars, use:

```sh

node examples/example3.js -o 'mico?cols=status,name,p99,ops,samples,*p99&sort=p99' --no-bail

```

That will output something similar to:

```txt

   s name             p99           ops           samples      *p99   

  --------------------------------------------------------------------

   ✔ sync3         🕛  121ns   ~22,766,507/s   |11,043,876|   × 1.00  

   ✔ callback3     🕐  130ns   ~21,984,471/s   |12,243,370|   × 1.07  

   ✔ async3        🕘  231ns   ~ 6,471,422/s   | 7,071,764|   × 1.91  

   ✗ sync3error    Error: Intentional Test Error

```

With bar row:

```sh

node examples/example3.js -o 'mico?cols=status,name,p99,ops,samples,*p99,=p99.95&sort=p99' --no-bail

```

will output something similar to:

```txt

   s name             p99           ops           samples      *p99   

  --------------------------------------------------------------------

   ✔ sync3         🕛  130ns   ~21,853,117/s   |10,993,846|   × 1.00  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜶘𜴦🮔

   ✔ callback3     🕛  130ns   ~21,662,141/s   |11,708,079|   × 1.00  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴦🮔

   ✔ async3        🕗  231ns   ~ 6,457,818/s   | 7,105,622|   × 1.78  

  🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂🮂𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜴢𜶘𜶘𜶫🮔🮔

   ✗ sync3error    Error: Intentional Test Error

  🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔🮔

```