@resyncnz/nexus-data

Loads Nexus test data into Playwright (and any Node test script) at run time, and reserves consumable rows for a CI run. It reads the data snapshot Nexus writes onto Jira issues, or an offline JSON snapshot file exported from Nexus. Every read is verified against the snapshot's sha256 checksum.

Node 18 or later. No dependency on Forge code.

npm install --save-dev @resyncnz/nexus-data

Configuration (environment variables only)

| Variable | Used for | |---|---| | NEXUS_JIRA_SITE | acme.atlassian.net (https only) | | NEXUS_JIRA_EMAIL, NEXUS_JIRA_TOKEN | A service account (and its Atlassian API token) that can browse the project | | NEXUS_DATA_FILE | Offline mode: path to an "Export JSON snapshot" file. Jira is not contacted | | NEXUS_CI_URL, NEXUS_API_KEY | reserveRows only: the Nexus CI API URL and the project API key |

Errors are NexusDataError with a code. Messages name the issue key, property key and HTTP status only, never a row value, a token or a URL, so they are safe in a CI log.

Load data

import { loadTestData } from '@resyncnz/nexus-data';

const data = await loadTestData({ issueKey: 'PAY-123' }); // a Test Case, or a Test Execution
for (const row of data.rows) {
  console.log(row.rowKey, row.values.email);
}
const one = data.byKey('valid-user'); // throws row-not-found

A Test Case carries its linked version (pinned, or the latest published). A Test Execution carries the version frozen when the run was planned with a data binding; use it in CI when the run must be reproducible.

Reserve consumable rows

import { reserveRows } from '@resyncnz/nexus-data';

const reservation = await reserveRows({ executionKey: 'PAY-900', count: 5, environment: 'staging' });
// reservation.status is 'granted' or 'partial'; reservation.rows holds only the granted rows.
try {
  // ... run tests with reservation.rows
  await reservation.consume(); // or report results with &dataSet= and the row key
} catch (err) {
  await reservation.release();
  throw err;
}

At most 200 rows per reservation. Pass the same externalId to retry safely.

Playwright

@resyncnz/nexus-data/playwright returns plain fixture definitions (nexusDataFixtures, nexusReservationFixtures). To declare one test per row, load the data at the top of the spec file. See examples/playwright/.

Offline mode

In Nexus, open the data set version and choose Export JSON snapshot. Set NEXUS_DATA_FILE=./payments.snapshot.json. The file is { "kind": "nexus.testdata.snapshot", "schemaVersion": 1, "manifest": {...}, "chunks": [...] }. Editing any value makes the checksum fail. See docs/automation-test-data.md for pytest and JUnit 5 examples.

Limits

From 0.1.1, timeoutMs must be a positive finite number (invalid-argument otherwise), and the reserve, release and consume requests have a 30 s time limit and are tried up to 3 times on a 429 or 5xx (Retry-After honoured, waits capped at 60 s); other 4xx answers are never retried.

• sensitive sets are never written to Jira. masked sets only when the project setting "Allow masked data in Jira snapshots" is on.
• Snapshots over 250 chunks (about 7.5 MB) are not written.
• Test Execution snapshots are frozen and are not retracted if the set is later reclassified.

Develop

npm run build, npm test (node:test, 31 tests).

Licence

MIT. © 2026 Resync Consulting Limited. See LICENSE.