Yonkers

Yonkers is a library and collection of services for distributed npm-centric debugging and testing across a swarm of connected agents. Each agent connects to a centralized relay from which controllers can pass commands to the agents.

Installation

Requires Node.js 14+

npm install -g yonkers

Usage

The centerpiece of Yonkers is the relay, of which exactly one is needed. To start a relay, do:

yonkers relay [options]

See yonkers help relay for the available options.

Next, start up one or more agents, ideally distributed across diverse machine types and network conditions:

yonkers agent [options]

See yonkers help agent for the available options.

Finally, point a controller at the relay and ask the relay to broadcast and run an npm package on the connected agents:

yonkers controller [options] run <pkg> <command> [args...]

See yonkers help controller for the available options.

<pkg> can be anything resolvable by npm install. If your package resides on your local disk, which it often will, you can point to it via the file: protocol or by using a relative path. <command> and [args...] should specify the command you wish to run in context of the package. A common use case is to broadcast and test a package, which can be done like this:

yonkers controller [options] run my-package npm test

To broadcast and test the package in your current work directory, do:

yonkers controller [options] run . npm test

To bind to network services, such as the V8 Inspector Protocol, use the --bind flag:

yonkers controller [options] run --bind 9229 . node --inspect server.js

For more information on the available commands, see yonkers help.

Configuration

As an alternative to repetitively passing options to the various commands in Yonkers, a configuration file can instead be used to set the default values of the corresponding options. Options passed directly to commands therefore always take precedence.

To get the location of the configuration file, do:

yonkers config path

The schema of the configuration file can be found in the lib/config.js module. While the file can be edited by hand, we recommend using the yonkers config set command to ensure that the file adheres to the schema:

yonkers config set <key> <value>

For options that aren't booleans, numbers, or strings, use the --json option and pass a JSON string as the value:

yonkers config set <key> --json '<value>'