istanbul-lib-processinfo

What is istanbul-lib-processinfo?

The istanbul-lib-processinfo package is part of the Istanbul code coverage ecosystem. It is responsible for managing and tracking process information for the purpose of code coverage analysis. This package helps in collecting and storing data about the execution of test processes, which is crucial for generating accurate code coverage reports.

What are istanbul-lib-processinfo's main functionalities?

ProcessInfo Creation

This feature allows the creation of a ProcessInfo object for a given process ID. The object contains metadata about the process, such as coverage data, which can be used for reporting.

const { create } = require('istanbul-lib-processinfo');
const processInfo = create(process.pid);

Writing ProcessInfo to Disk

This feature enables the ProcessInfo object to be serialized and written to disk. This is useful for persisting coverage information between test runs or for later analysis.

processInfo.write();

Loading ProcessInfo from Disk

This feature allows loading previously saved ProcessInfo objects from disk. This is useful for aggregating coverage data from multiple test runs.

const { loadProcessInfos } = require('istanbul-lib-processinfo');
const processInfos = loadProcessInfos();

Other packages similar to istanbul-lib-processinfo

nyc

NYC is a command-line tool that provides a wrapper around the Istanbul code coverage tool. It offers similar functionality for tracking process information for coverage reporting. NYC is more user-friendly and provides additional features like support for subprocesses and integration with various testing frameworks.

c8

C8 is another code coverage tool that leverages the built-in V8 coverage functionality. It provides similar process tracking and coverage reporting features but does so using native V8 coverage instead of instrumenting the code like Istanbul does. C8 is known for its simplicity and speed compared to Istanbul-based tools.

coveralls

Coveralls is a web service that helps you track your code coverage over time, and ensure that all your new code is fully covered. While it does not directly handle process information like istanbul-lib-processinfo, it integrates with coverage tools to provide a hosted solution for tracking and displaying code coverage metrics.

README

istanbul-lib-processinfo

A utility for managing the processinfo folder that NYC uses.

This is intended to be used along with NYC, but can also be used by other tools that wish to consume NYC's processinfo data.

API

class ProcessInfo

A representation of information about a single process.

constructor(fields)

Pass in fields that will be printed to the processinfo file. Several defaults will be provided if not specified.

async processInfo.save()

Write this process info to disk. This works by passing the ProcessInfo object to JSON.stringify, and writing to ${this.directory}/${this.uuid}.json.

processInfo.saveSync()

The synchronous version of .save().

async processInfo.getCoverageMap(nyc)

Get a merged coverage map of the current process, as well as any child processes. This should only be called during tree rendering, as it depends on child nodes being present in the nodes array.

The nyc instance is required to load the report information and apply sourcemaps properly.

processInfo.label

A read-only string for when archy prints the process tree.

processInfo.nodes

A list of the child nodes used during tree rendering.

processInfo.directory

If a process will be saved, it must have a directory included in the list of fields. This property is not saved to the processinfo file.

class ProcessDB

A utility for interacting with the collection of ProcessInfo files in the processinfo folder.

constructor(directory)

Supply the directory where processinfo files are found. This should be the full path, something like ${cwd}/.nyc_output/processinfo.

processDB.directory

A read-only property showing the directory where this object is working.

processDB.nodes

A list of child ProcessInfo nodes used in tree printing.

processDB.label

The string 'nyc', used as the default root node in the archy tree rendering.

async processDB.writeIndex()

Create the index.json file in the processinfo folder, which is required for tree generation and expunging.

WARNING: Index writing is non-atomic, and should not be performed by multiple processes.

async processDB.readIndex()

Read and return the contents of the index.json file. If the index.json is not present or not valid, then it will attempt to generate one.

async processDB.readProcessInfos()

Read all the data files in the processinfo folder, and return an object mapping the file basename to the resulting object. Used in tree generation.

async processDB.renderTree(nyc)

Render the tree as a string using archy, suitable for printing to the terminal.

async processDB.buildProcessTree()

Build the hierarchical tree of nodes for tree rendering. Populates the nodes array of this object and all ProcessInfo objects in the tree.

async processDB.getCoverageMap(nyc)

Used in tree rendering, to show the total coverage of all the processinfo files in the data folder.

async processDB.spawn(name, file, args, options)

Spawn a child process with a unique name provided by the caller. This name is stored as the externalId property in the child process's ProcessInfo data, and is tracked in the externalIds section of the index.

Note that if the current process is not already wrapped by nyc, then you must prefix the spawned program with nyc, in order for this to take effect. For example, instead of processDB.spawn('foo', 'node', ['foo.js']), you would run processDB.spawn('foo', 'nyc', ['node', 'foo.js']).

If a process with that name already exists in the index, then it will be expunged.

Unlike child_process.spawn this function returns a Promise which resolves to the ChildProcess object.

WARNING: Calling expunge (which this method does) will result in the index being out of date. It is the caller's responsibility to call processDB.writeIndex() when all named processes are completed.

async processDB.expunge(name)

If a process exists in the process info data folder with the specified name (ie, it had previously been run with processDB.spawn(name, ...)) then the coverage and processinfo files for it and all of its children are removed.

This allows for a test harness to re-run or resume test suites, without spurious coverage results.

WARNING: Calling expunge will result in the index being out of date. It is the caller's responsibility to call processDB.writeIndex() when all named processes are completed.

DATA STRUCTURES and FILES

ProcessInfo files MUST match the following structure:

{
  "uuid": "UUID of the process itself",
  "parent": "UUID of the parent process, or null",
  "pid": Number,
  "ppid": Number (pid of parent process),
  "argv": Array<String>,
  "execArgv": Array<String>,
  "cwd": path,
  "time": Number (timestamp in ms),
  "coverageFilename": "Path to NYC coverage info for this process",
  "externalId": "The externally specified name for this process, or null",
}

The index file is saved to ${this.directory}/index.json. It has the following structure:

{
  "processes": {
    "<uuid>": {
      "parent": "parent uuid, or null",
      "children": ["children", "uuids", "or empty array"],
      "externalId": "externally specified name, if provided"
    },
    ...
  },
  "files": {
    "/path/to/covered/file.js": [
      "<uuids of processes that covered this file>",
      ...
    ],
    ...
  },
  "externalIds": {
    "externally specified name": {
      "root": "<uuid of process run under this name>",
      "children": [
        "<uuids of all descendant processes from this point in the tree>",
        ...
      ]
    },
    ...
  }
}