Nominal Pizza Masticator

    jest-measure

    0.0.14 • Public • Published

    Jest Measure

    The Jest Measure library implements APIs for writing benchmaks to profile and verify the performance of your code when using the Jest unit testing library.

    Getting Started

    To get started simply install the library:

    yarn add jest-measure
    

    To write your first test just import the measure method from the library and use it as you would use the normal test method.

    const { measure } = require('jest-measure')
    
    measure('your test name', () => {
        return {
            metricYouHaveMeasured: 1000
        }
    })
    

    The first time you run your test you we will need to record a baseline to compare it against.

    To do this just run jest with UPDATE_BENCHMARK set to true

    UPDATE_BENCHMARK=true jest
    

    This will generate the baseline metrics and store them under a __benchmark__ folder in a similar manner to snapshot tests.

    After this we can now run our benchmarks to check if the performance has degraded.

    By default benchmark don't run so we need to pass RUN_BENCHMARK with a value of true

    RUN_BENCHMARK=true jest
    

    We can get a table of our our baseline metrics by running the jest-measure command.

    yarn run jest-measure
    

    You will see the last updated list of benchmark tests and the metrics we use to compare our tests with.

    Basic Usage

    The easiest way to measure and return metrics to be compared is by returning an dictionary containing the name and value of each metric.

    const { measure } = require('jest-measure')
    
    measure('A long method', () => {
        return {
            pageLoadTime: 10,
            totalTime: 1000
        }
    })
    

    The pageLoadTime and totalTime metrics will now appear in the list of metrics when running jest-measure

    Performance API Usage

    Jest measure supports using the Performance API to more accuratley collect metrics.

    Every call to performance.measure will automatically be collected and added to the list of metrics when running jest-measure

    const { performance, measure } = require('jest-measure')
    
    measure('An async task', async () => {
    
        performance.mark('load')
    
        onLoad(() => {
            performance.mark('loaded')
        })
    
        await waitUntilLoaded()
        
        performance.measure('load-time', 'load', 'loaded')
    })
    

    Measurement Objects

    We also have the measurement objects which provide a high level API to simplify the use of the performance API.

    For example we can use a Stopwatch to measure the time taken between key events in our application.

    const { Stopwatch, measure } = require('jest-measure')
    
    measure('An async task', async () => {
    
        const s = new Stopwatch()
    
        onLoad(() => {
            s.lap('loaded')
        })
    
        await waitUnitlLoaded()
    
        s.measure()
    })
    

    Sometimes the subject we are measuring can spawn concurrent operations we need to measure independently.

    We can use sub stopwatches for this which will allow you to measure the time between laps starting from the last lap of the main stopwatch.

    const { Stopwatch, measure } = require('jest-measure')
    
    measure('An async task', async () => {
    
        const s = new Stopwatch()
    
        onLoad(() => {
            s.lap('loaded')
    
            loadFirstPage(() => {
                const p = s.subStopwatchFromLastLap()
                p.lap('first-page-loaded')
            })
    
            loadLastPage(() => {
                const p = s.subStopwatchFromLastLap()
                p.lap('last-page-loaded')
            })
        })
    
        await waitUnilLoaded()
        await waitUnilPagesLoaded()
    
        s.measure()
    })
    

    All of these sub-stopwatches will have their metrics automatically measured for you when you call measure on the main stopwatch.

    Reporter API

    If you want to process reports to output them into other tools such as in a comment in a Pull Request using DangerJS.

    Then you can use Reporter API in your scripts to consume Jest Measure reports.

    const { ReportFormatter } = require('jest-measure')
    const Table = require('cli-table')
    
    const table = new Table({
        head: [
            'Name',
            'Benchmark',
            'Min (ms)',
            'Mean (ms)',
            'Mean Error (%)',
            'Difference (%)'
        ]
    });
    
    const formatter = new ReportFormatter((metric, stats) => {
    
        let row = {};
    
        row[metric] = [
            stats.mean.toFixed(2),
            stats.min.toFixed(2),
            stats.mean.toFixed(2),
            stats.error.toFixed(2),
            stats.difference.toFixed(2) * 100
        ];
    
        table.push(row)
    })
    
    
    formatter.formatReports()
    console.log(table.toString());
    

    The formatter will try to collect all reports under the current directory and will call the callback for each metric to be formatted.

    The example above formats the metrics into a table for the CLI.

    Options

    To configure options for Jest Measure such as how many iterations it will run a test for then simply add a jestMeasure section to your package.json and add any of the avaliable options

    {
      "name": "my-app",
      ...
      "jestBenchmark": {
          "benchmarkRounds": 50
      },
    }
    

    Install

    npm i jest-measure

    DownloadsWeekly Downloads

    77

    Version

    0.0.14

    License

    MIT

    Unpacked Size

    19.3 kB

    Total Files

    16

    Last publish

    Collaborators

    • jscampbell.05