npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@token-cjg/leakage

v0.6.0

Published

Memory leak testing for node. Javascript memory footprinting using your favorite test runner.

Downloads

1

Readme

Leakage - Memory Leak Testing for Node

Build Status NPM Version JavaScript Style Guide

Write leakage tests using Mocha or another test runner of your choice.

Does not only support spotting and fixing memory leaks, but writing tests also enables you to prevent regressions and show that the code does not leak.

Table of Contents

Installation

npm install --save-dev leakage
# or
yarn --dev leakage

Development

To build locally, you will need asdf (https://asdf-vm.com/). Installation instructions vary by operating system but are fairly self-explanatory.

You will also need asdf-nodejs (https://github.com/asdf-vm/asdf-nodejs).

Once you've installed the tooling, run

asdf install nodejs 16.15.0 && asdf reshim nodejs

To doublecheck that you have the correct node, run node --version and verify that the output is v16.15.0 (or at least consistent with what is in .tool-versions).

You should then be able to npm install and plug away at the codebase.

Usage

In theory you could use any testing framework to run leakage tests. In practice, though, you want to use one that generates a minimal memory overhead itself. We suggest using Mocha or Tape, since they are quite simple and don't produce much noise in the captured data.

Usage with Mocha

import myLib from 'my-lib'
import { iterate } from 'leakage'

describe('myLib', () => {
  it('does not leak when doing stuff', () => {
    iterate(() => {
      const instance = myLib.createInstance()
      instance.doStuff('foo', 'bar')
    })
  })
})

iterate() will run the function several times, create a heap snapshot and repeat that process until there is a set of heap diffs. If a memory leak has been detected an error with some debugging information will be thrown.

Make sure you run all tests serially in order to get clean heap diffs. Mocha should run them sequentially by default.

Use iterate.async() for asynchronous test code. See Asynchronous Tests and API for details.

Usage with tape

import test from 'tape'
import myLib from 'my-lib'
import { iterate } from 'leakage'

test('myLib does not leak when doing stuff', () => {
  iterate(() => {
    const instance = myLib.createInstance()
    instance.doStuff('foo', 'bar')
  })
})

Asynchronous Tests

Use iterate.async() to test asynchronous code. The iterator function is supposed to return a promise and iterate.async() will return a promise itself. In case of a memory leak that returned promise will be rejected instead of iterate failing synchronously.

Do not forget to return the promise in your test or use async functions and await iterate.async().

import fetch from 'isomorphic-fetch'
import { iterate } from 'leakage'

describe('isomorphic-fetch', () => {
  it('does not leak when requesting data and parsing JSON', async () => {
    await iterate.async(async () => {
      const response = await fetch()
      await response.json()
    })
  })
})

Memory Management in JS?

Since every JavaScript runtime comes with a garbage collector you should not have to care about memory allocation / freeing memory at all, right? Sadly not.

Memory leaks are a common problem in most programming languages. Memory gets allocated, but is not freed again, leading to a steadily increasing usage of memory. Since the memory you use is finite your application will eventually crash or become so slow it is rendered useless.

As soon as you still have a reference to an object, array, arrow function, ... you do not use anymore you might have already created a memory leak. Creating an object (incl. arrays and closures) means allocating heap memory that will be freed by the next automatic garbage collection only if all references to this object have vanished.

API

iterate(syncIterator: Function, options: ?Object): Result

Test for memory leaks. Will throw an error when a leak is recognized.

syncIterator can be any synchronous function. Let it perform your operations you want to test for memory leaks.

options.iterations is the number the iterator function is run for each heap diff / garbage collection. Defaults to 30.

options.gcollections is the number of heap snapshots to create. Defaults to 60.

iterate.async(asyncIterator: Function, options: ?Object): Promise

Test for memory leaks. Will return a rejecting promise when a leak is recognized.

asyncIterator can be any asynchronous function. Let it perform your operations you want to test for memory leaks.

options.iterations is the number the iterator function is run for each heap diff / garbage collection. Defaults to 30.

options.gcollections is the number of heap snapshots to create. Defaults to 60.

Result object

Properties:

  • heapDiffs - An array of heap diffs as created by node-memwatch
  • iterations - The number of iterator runs per heap diff
  • gcollections - The number of garbage collections / heap diffs performed

Methods:

  • printSummary(title: ?String, log: ?Function) - Prints a short summary. Can pass a title to print. log is the function used to output the summary line by line. Defaults to console.log.

MemoryLeakError

Memory leak errors are instances of this custom error. You can use it to check if an error is really a memory leak error or just a generic kind of problem (like a broken reference).

Import it as const { MemoryLeakError } = require('leakage').

CLI Parameters

You can pass special CLI parameters for leakage to your test runner:

mocha test/sample.test.js --heap-file heap-diff.json

--heap-file

Will make the library write a detailed heap diff JSON to the file system. Make sure you only run a single test using it.only. Otherwise you will only find the heap diff of the last test in the file. Useful for debugging.

Under the Hood

Leakage uses node-memwatch to trigger the garbage collector and create heap diffs.

You just specify an iterator function. It will be run 30 times by default then a garbage collection will be performed and a heap snapshot will be made. This process is iterated 6 times by default to collect several heap diffs, since especially in async tests there is always a bit of background noise.

If the heap size increased over more than [heapDiffCount * 2 / 3] subsequent garbage collections an error is thrown.

Travis CI

You might want your leakage tests to be run by your CI service. There is an issue with Travis CI's linux containers, g++ and a transitive dependency of node-memwatch (nan).

Fortunately there is a fix: You need to install and use version 4.8 of g++ in order to compile the dependency.

Have a look at leakage's .travis.yml file to see how it can be done or find further details by @btmills in this issue.

FAQ

If you see an error like Error: Timeout of 2000ms exceeded. (...) it means that your test took so long that the test runner cancelled it.

You can easily increase the timeout. Have a look at your test runner's documentation for that. When using Mocha, for instance, you can run it with --timeout 10000 to increase the timeout to 10000ms (10s).

Leakage tests are rather slow compared to usual unit tests, since heap snapshotting and diffing takes some time and has to be done several times per test.

You can try to reduce the number of heap diffs created, but beware that fewer heap diffs can result in less accurate results. See API for details.

Contribute

Got any feedback, suggestions, ...? Feel free to open an issue and share your thoughts!

Used it successfully or were unable to use it? Let us know!

Have an improvement? Open a pull request any time.

License

Released under the terms of the MIT license. See LICENSE for details.