{"id":19592312,"url":"https://github.com/smikhalevski/toofast","last_synced_at":"2025-04-23T04:53:12.212Z","repository":{"id":38011500,"uuid":"389641854","full_name":"smikhalevski/toofast","owner":"smikhalevski","description":"⚡️ The Node.js performance testing tool with unit-test-like API.","archived":false,"fork":false,"pushed_at":"2023-09-04T18:20:59.000Z","size":425,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-23T04:53:06.174Z","etag":null,"topics":["node","performance","test"],"latest_commit_sha":null,"homepage":"https://smikhalevski.github.io/toofast/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smikhalevski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-26T13:26:29.000Z","updated_at":"2024-10-10T08:04:41.000Z","dependencies_parsed_at":"2024-11-11T08:38:53.433Z","dependency_job_id":"02edb73d-9863-4d37-8f62-1bf01a939bca","html_url":"https://github.com/smikhalevski/toofast","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"1da7117b0e5008eceb805b36eafee139baec69c2"},"previous_names":["smikhalevski/perf-test"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikhalevski%2Ftoofast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikhalevski%2Ftoofast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikhalevski%2Ftoofast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smikhalevski%2Ftoofast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smikhalevski","download_url":"https://codeload.github.com/smikhalevski/toofast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250372946,"owners_count":21419722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node","performance","test"],"created_at":"2024-11-11T08:34:36.228Z","updated_at":"2025-04-23T04:53:12.193Z","avatar_url":"https://github.com/smikhalevski.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TooFast ⚡️ [![build](https://github.com/smikhalevski/toofast/actions/workflows/test.yml/badge.svg?branch=master\u0026event=push)](https://github.com/smikhalevski/toofast/actions/workflows/test.yml)\n\nThe Node.js performance testing tool with unit-test-like API.\n\n- Runs each test in a separate process;\n- Measures execution time using [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance);\n- Runs test functions in multiple batches to reduce garbage collection interference;\n- Warms up test functions;\n- Measures memory consumption using\n  [`process.memoryUsage`](https://nodejs.org/api/process.html#processmemoryusagerss).\n\n```shell\nnpm install toofast --save-dev\n```\n\n- [Usage](#usage)\n- [CLI options](#cli-options)\n- [Test API](#test-api)\n    - [`test`](#test)\n    - [`describe`](#describe)\n    - [Lifecycle hooks](#lifecycle-hooks)\n- [Test options](#test-options)\n- [Configuration](#configuration)\n\n# Usage\n\nLet's write a performance test for a function that computes a factorial.\n\nCreate a file `factorial.perf.js`:\n\n```ts\nfunction factorial(x) {\n  return x === 0 ? 1 : x * factorial(x - 1);\n}\n\ndescribe('factorial', () =\u003e {\n\n  test('of 33', measure =\u003e {\n    measure(() =\u003e {\n      factorial(33);\n    });\n  });\n\n  test('of 42', measure =\u003e {\n    measure(() =\u003e {\n      factorial(42);\n    });\n  });\n});\n```\n\nCall `toofast` in the same directory with this file:\n\n```shell\nnpx toofast\n```\n\n# CLI options\n\n```bash\ntoofast [options] ...files\n```\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003e...files\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe list of glob patterns of included test files. If config file was not found, then files that match `**/*.perf.js` are\nincluded.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003e-c \u0026lt;file\u0026gt;\u003c/code\u003e, \u003ccode\u003e--config \u0026lt;file\u0026gt;\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe [configuration](#configuration) file path.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003e-t \u0026lt;pattern\u0026gt;\u003c/code\u003e, \u003ccode\u003e--testNamePattern \u0026lt;pattern\u0026gt;\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe name glob pattern of `describe` and `test` blocks that should be run. If specified multiple times then blocks that\nmatch _any_ of the patterns are run.\n\n\u003c/dd\u003e\n\u003c/dl\u003e\n\n# Test API\n\n🔎 [Programmatic API documentation is available here.](https://smikhalevski.github.io/toofast/)\n\nTooFast injects several global callbacks in test files that register lifecycle hooks and trigger test execution.\n\n## `test`\n\nThe minimum setup that you need in a test file is the `test` callback which runs a test. For example, let's say there's\na function `factorial()` which performance must be measured. Your whole test could be:\n\n```ts\ntest('factorial of 33', measure =\u003e {\n  measure(() =\u003e {\n    factorial(33);\n  });\n});\n```\n\nThe `measure` callback starts the performance measurement. It can be invoked multiple times inside a `test` block to\ncollect a data population from which an average results are derived.\n\n```ts\ntest('factorial of 33 and 42', measure =\u003e {\n\n  measure(() =\u003e {\n    factorial(33);\n  });\n\n  measure(() =\u003e {\n    factorial(42);\n  });\n});\n```\n\nThe `measure` callback returns a promise that is resolved as soon as performance measurement is completed.\n\n[Test lifecycle](#lifecycle-hooks) is initiated for each `test` block and run in a separate process.\n\n## `describe`\n\nCreates a block that groups together several related tests.\n\n```ts\ndescribe('factorial', () =\u003e {\n\n  test('of 42', measure =\u003e {\n    measure(() =\u003e {\n      factorial(42);\n    });\n  });\n});\n```\n\n`describe` blocks can be nested:\n\n```ts\ndescribe('Math', () =\u003e {\n\n  describe('factorial', () =\u003e {\n    // Tests go here\n  });\n});\n```\n\n## Lifecycle hooks\n\nThere are several global functions injected by TooFast that register hooks. Hooks are invoked at different phases of the\nperformance test suite lifecycle: `beforeEach`, `afterEach`, `afterWarmup`, `beforeBatch`, `afterBatch`,\n`beforeIteration`, and `afterIteration`.\n\nThe chart below demonstrates when they are called.\n\n```mermaid\nflowchart TD\n\ndescribe --\u003e testLifecycle\n\nsubgraph testLifecycle [Test lifecycle]\n    direction LR\n\n    subgraph warmup [Warmup]\n        direction TB\n        warmupBeforeBatch(beforeBatch) --\u003e\n        warmupBeforeIteration(beforeIteration) --\u003e\n        warmupMeasure[measure] --\u003e\n        warmupAfterWarmup(afterWarmup) --\u003e\n        warmupAfterIteration(afterIteration) --\u003e\n        warmupAfterBatch(afterBatch)\n    end\n\n    subgraph batch [Batch]\n        direction TB\n        testBeforeBatch(beforeBatch) --\u003e\n        testBeforeIteration(beforeIteration) --\u003e\n        testMeasure[measure] --\u003e\n        testAfterIteration(afterIteration) --\u003e\n        testAfterBatch(afterBatch)\n    end\n\n    beforeEach(beforeEach) --\u003e\n    test --\u003e\n    warmup --\u003e\n    batch --\u003e\n    afterEach(afterEach)\nend\n```\n\nHooks can be registered at root level, or inside a `describe` or `test` block. Registered hooks affect `measure` calls\nthat are nested in the same enclosing block.\n\nHooks are always registered before any measurements are started, so the code below would first register `beforeEach` and\n`beforeIteration` hooks and only after that would run `measure`.\n\n```ts\ndescribe('factorial', () =\u003e {\n\n  beforeEach(() =\u003e {\n    // Runs before each test\n  });\n\n  test('of 42', measure =\u003e {\n    measure(() =\u003e {\n      factorial(42);\n    });\n\n    beforeIteration(() =\u003e {\n      // Runs before each measurement iteration\n    });\n  });\n});\n```\n\n# Test options\n\nProvide [test options](https://smikhalevski.github.io/toofast/interfaces/TestOptions.html) to [`test`](#test),\n[`describe`](#describe) and `measure` functions. Options of nested blocks are merged.\n\n```ts\ndescribe('factorial', { batchTimeout: 500 }, () =\u003e {\n\n  test('of 42', { targetRme: 0.2 }, measure =\u003e {\n\n    measure({ warmupIterationCount: 5 }, () =\u003e {\n      factorial(42);\n    });\n  });\n});\n```\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003emeasureTimeout\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe maximum measure duration in milliseconds. Doesn't include the duration of warmup iterations. Defaults to 10_000.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003etargetRme\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe maximum relative margin of error that must be reached for each measurement [0, 1]. Defaults to 0.01.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003ewarmupIterationCount\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe maximum number of warmup iterations that are run before each measurement. Defaults to 1. Set to 0 to disable warmup.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003ebatchIterationCount\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe maximum number of iterations in a batch. Unlimited by default.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003ebatchTimeout\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe maximum duration of batched measurements in milliseconds. Defaults to 1_000.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003ebatchIntermissionTimeout\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe delay between batched measurements in milliseconds. VM is expected to run garbage collector during this delay.\nDefaults to 200.\n\n\u003c/dd\u003e\n\u003c/dl\u003e\n\nYou can also [register hooks](https://smikhalevski.github.io/toofast/interfaces/MeasureOptions.html) specific for a\nparticular `measure` call.\n\n```ts\ntest('factorial', measure =\u003e {\n  measure(\n    {\n      beforeBatch() {\n        gc();\n      }\n    },\n    () =\u003e {\n      factorial(42);\n    }\n  );\n});\n```\n\n# Configuration\n\nBy default, TooFast searches for `.toofastrc`, `toofast.json`, or `toofast.config.js` in the current directory.\n\nConfiguration file should export the object that satisfies the\n[`Config`](https://smikhalevski.github.io/toofast/interfaces/Config.html) interface:\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003etestOptions\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe default [test options](#test-options) used for all tests.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003einclude\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe array of glob patterns of included test files. File paths are resolved relative to the config file.\n\n\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003esetupFiles\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\n\nThe array of glob patters of files that are evaluated in the test environment before any test suites are run. File paths\nare resolved relative to the config file.\n\n\u003c/dd\u003e\n\u003c/dl\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmikhalevski%2Ftoofast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmikhalevski%2Ftoofast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmikhalevski%2Ftoofast/lists"}