@nats-io/nst

Status: internal/unsupported. @nats-io/nst exists to support tests within the nats.js repo. It is published so the test suite can install it like any other workspace member, but it is not a stable public API. Symbols, behavior, and signatures may change without notice. Do not depend on it outside this repo without expecting churn.

Shared test utilities for nats.js modules. Provides:

• NatsServer — spawns/manages a nats-server binary for tests (single, cluster, leafnode).
• setup / cleanup — quick test fixtures returning a server + connection.
• jetstreamServerConf / jetstreamExportServerConf / wsServerConf — config builders.
• Lock, check, assertBetween, flakyTest — small test helpers.
• Connection, TestServer — fake-NATS TCP server for protocol tests.
• registerConnect / getConnect — transport injection (see below).

Runs on Deno and Node.js (≥ 20). The package never imports a transport — the caller registers connect from their transport package.

Requirements

• nats-server binary on PATH. Install: https://github.com/nats-io/nats-server/releases
• Node.js ≥ 20 or Deno ≥ 2.

Install

# npm
npm i -D @nats-io/nst

# JSR / Deno
deno add jsr:@nats-io/nst

@nats-io/nats-core is a peer dependency — your project provides it.

Bootstrap

@nats-io/nst does not import a transport. Each test runtime must register one once before calling setup() or NatsServer.connect():

Deno (transport-deno)

// tests/connect.ts
import { connect } from "@nats-io/transport-deno";
import { registerConnect } from "@nats-io/nst";
registerConnect(connect);
export { connect };

Node.js (transport-node)

// tests/connect.js
const { connect } = require("@nats-io/transport-node");
const { registerConnect } = require("@nats-io/nst");
registerConnect(connect);
module.exports = { connect };

Tests then import setup, cleanup, NatsServer, etc. from @nats-io/nst and the registered connect is used internally.

Example

import { cleanup, jetstreamServerConf, setup } from "@nats-io/nst";
import "./connect.ts";

Deno.test("publish/subscribe", async () => {
  const { ns, nc } = await setup(jetstreamServerConf());
  // ... use nc ...
  await cleanup(ns, nc);
});

Cluster / leafnode

const cluster = await NatsServer.cluster(3);
// ...
await NatsServer.stopAll(cluster, true);

NatsServer exposes varz(), jsz(), connz(), leafz() for monitoring endpoint queries.

License

Apache 2.0