![](\"https://user-images.githubusercontent.com/22956519/66310240-f96b9480-e90b-11e9-9add-4c8bc8ea8707.png\")
\n\n \n
\n Zakzak makes microbenchmarking in node.js projects easier and automated, by using a \"unit test\"-like approach.\n
\n\n\n## Table of Contents\n\n\n\n- [Usage](#usage)\n- [Documentation](#documentation)\n - [Define benchmarks](#define-benchmarks)\n - [Structure the benchmarks using suites](#structure-the-benchmarks-using-suites)\n - [Setup and Teardown](#setup-and-teardown)\n - [Async Benchmarks](#async-benchmarks)\n - [Memory benchmark](#memory-benchmark)\n - [Configuration](#configuration)\n - [CLI](#cli)\n - [Custom Exporter](#custom-exporter)\n - [Typescript support](#typescript-support)\n- [Installation](#installation)\n - [Prerequisites](#prerequisites)\n - [Using npm](#using-npm)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n\n\n## Usage\n\nSimilar to unit tests, you create `*.benchmark.js` files, in which you define your benchmarks. If you've worked with mocha.js before, you will find this approach familiar.\n\n```ts\nimport { suite, benchmark } from \"@dynatrace/zakzak\";\n\nsuite(\"crypto-functions\", () => {\n benchmark(\"encryptMessage\", () => {\n const msg = \"foobar\";\n encryptMessage(msg);\n });\n\n benchmark(\"hashSomePassword\", () => {\n hashSomePassword(\"secret-pw\");\n });\n});\n```\n\nThen you run the benchmarks, using the cli.\n\n```bash\n$ zakzak --path ./src/benchmarks --exporter json\n```\n\nYou can also take a look at the demo project, to see how zakzak is used.\n\n## Documentation\n\n### Define benchmarks\n\nBenchmarks are easily defined. Just write the following and make sure `zakzak` reads the file where the benchmark was defined.\n\n```ts\nbenchmark(\"some-name\", () => {\n fibonacci(5000);\n});\n```\n\nI recommend putting these definitions in separate files, and to name those files with a specific pattern, so `zakzak` can find them using a `glob` pattern. Zakzak uses [globby](https://github.com/sindresorhus/globby) internally. The default filepattern is `*.benchmark.js`, but you can provide a different pattern using CLI params or the config.\n\nWhile it is possible to define these benchmarks in your source code, I highly advise against it. `zakzak` uses `require` to read all the files you point it to and thus executes them.\n\n### Structure the benchmarks using suites\n\nA suite is just a fancy way of grouping benchmarks or suites together and applying options.\n\n```ts\nsuite(\"suite-name\", () => {\n benchmark(\"some-name\", () => {\n fibonacci(5000);\n });\n});\n```\n\nSuites can also be nested and contain other suites, building a hierarchy.\n\n```ts\nsuite(\"momma-suite\", () => {\n benchmark(\"some-name\", () => {\n fibonacci(5000);\n });\n suite(\"suite child\", () => {\n suite(\"suite niece\", () => {\n suite(\"such a 'suite' boy\", () => {\n benchmark(\"benchy\", () => {\n fibonacci(5000);\n });\n });\n });\n benchmark(\"benchling\", () => {\n fibonacci(5000);\n });\n });\n});\n```\n\nThere is no limit as to how many nested levels or children you can have.\n\n**Note**: Every file is per default a suite. So even if you don't define any suites, a benchmark will always be a child of a suite. This is done to keep track of the structure and location of benchmarks.\n\n### Setup and Teardown\n\n`setup()` and `teardown()` are two more functions, that can be utilized in the .benchmark.ts files. As their names suggest, they run setup and teardown code, before and after the benchmarking. Important to note is, that code is only run once before and/or after the benchmarking, and is not repeated everytime the benchmarking code runs.\n\n```ts\nsuite(\"demo\", ()=>{\n setup(()=>{\n dbconnection = connectToDb();\n });\n benchmark(\"some-db-stuff\",()=>{\n ...\n });\n teardown(()=>{\n dbconnection.close();\n });\n});\n```\n\nThe hierarchy system using suites can be also be leveraged by lifetime functions, such as setup and teardown. Lifetime functions from a parent suite also apply to all child suites, however there is a order in which parent and child lifetime functions are executed.\nFor setup functions it works like this.\n\n```ts\nsuite(\"a\", () => {\n setup(() => {}); // is executed first\n suite(\"b\", () => {\n setup(() => {}); // is executed second\n });\n});\n```\n\nFor teardown functions the order is reversed.\n\n```ts\nsuite(\"a\", () => {\n teardown(() => {}); // is executed second\n suite(\"b\", () => {\n teardown(() => {}); // is executed first\n });\n});\n```\n\n### Async Benchmarks\n\nTo Benchmark asynchronous stuff, either return a Promise that resolves, onces you're finished or mark you function as `async` (which makes it return a promise).\n\n```ts\nbenchmark(\"promise\", () => {\n return willReturnAPromise();\n});\n\nbenchmark(\"async-await\", async () => {\n doStuffThatsAsync();\n});\n```\n\n### Memory benchmark\n\nYou can also get some memory readings from the benchmarks. For that you just have to set the `memoryBenchmark` flag in the configuration to true.\n\n### Configuration\n\nThere multiple ways to configure your benchmarks:\n\n- Using the CLI params\n- Using a config\n- In the benchmark files using the options param\n- Not at all. Just use the default values\n\nThese options are non exclusive, meaning that if you use one of these options, that does not prohibit you from using one of the others additionally. If two configuration types however define a value for the same option, the one with higher priority will be taken.\nThe priorities are the following, listed from low to high.\n\n```\nDefault -> Config -> CLI Param -> Suite options -> Benchmark options\n```\n\nIn the benchmark files, you apply options like this.\n\n```ts\nbenchmark(\n \"snowflake-with-custom-needs\",\n () => {\n fibonacci(5000);\n },\n { minSamples: 20, maxSamples: 50 }, // options\n);\n```\n\nYou can also pass the options to a suite, which will then apply those to it's children. However, if an enclosed suite or benchmark has it's own options, then those will be prioritized over the options of the parent suite.\n\n```ts\nsuite(\n \"momma-suite\",\n () => {\n // has minSamples: 10\n benchmark(\"some-name\", () => {\n fibonacci(5000);\n });\n },\n { minSamples: 10 },\n);\n```\n\nDefining options is optional, no matter what type of configuration is used.\nIf none of the configuration types provides a value for an options field, then the default values of the framework will be used.\n\n### CLI\n\nThe CLI tool is used to find, structure and run the benchmarks. Per default, it will look for a `zakzak.config.json` in the current working directory. If it doesn't find this config, it will use the default values of the framework. You can also override some of the settings using the CLI params.\n\n- **`-v, --version`:** Output the version number of zakzak.\n- **`-p, --pattern![\"Zakzak](\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\"){kind=icon}
\n ![](\"https://img.shields.io/npm/v/@dynatrace/zakzak\")
\n