diff --git a/doc/contributing/benchmark-tests.md b/doc/contributing/benchmark-tests.md new file mode 100644 index 00000000000..141475eccb9 --- /dev/null +++ b/doc/contributing/benchmark-tests.md @@ -0,0 +1,53 @@ + +# Performance Benchmark Testing Guide + +Benchmark tests are intended to measure performance of small units of code. + +It is recommended that operations that have a high impact on the performance of the SDK (or potential for) are accompanied by a benchmark test. This helps end-users understand the performance trend over time, and it also helps maintainers catch performance regressions. + +Benchmark tests are run automatically with every release, and the results are available at . + +## Running benchmark tests + +Performance benchmark tests can be run from the root for all modules or from a single module directory only for that module: + +``` bash +# benchmark all modules +npm run test:bench + +# benchmark a single module +cd packages/opentelemetry-sdk-trace-base +npm run test:bench +``` + +## Adding a benchmark test + +Unlike unit tests, benchmark tests should be written in plain JavaScript (not Typescript). + +Add a new test file in folder `test/performance/benchmark` using the following as a template: + +``` javascript +const Benchmark = require('benchmark'); + +const suite = new Benchmark.Suite(); + +suite.on('cycle', event => { + console.log(String(event.target)); +}); + +suite.add('new benchmark test', function() { + // write code to test ... +}); + +suite.run(); +``` + +## Automatically running benchmark tests + +If you want your test to run automatically with every release (to track trend over time), register the new test file by requiring it in `test/performance/benchmark/index.js`. + +Add the `test:bench` script in package.json, if the module does not contain. + +``` json +"test:bench": "node test/performance/benchmark/index.js" +```