API Reference

Quick reference for @vaagatech/snapline-core. Install one package — it re-exports engine, adapters, and utilities.

Core orchestration

Export	Description
`testSuite(name, config)`	Run one or more test modes; returns `TestSuiteResult`
`runApiFixtureCases(options)`	HTTP fixture cases from `fixtures/cases/`
`runSnaplineFixtureCases(options)`	Offline fixture cases (`live.json` vs `expected.json`)

`testSuite` config

Field	Description
`auth`	Optional `auth.oauth2()`, `auth.openid()`, or `auth.basic()`
`baseUrl`	Prepended to relative API endpoints
`api`	API ↔ JSON fixture
`dbComparison`	DB ↔ DB (SQL or NoSQL)
`apiToDb`	API response vs DB row
`dbToApi`	DB row vs API response (`inputFromDb`)
`publishAndPoll`	Publish to queue → poll DB, file, or response topic
`fetchImpl`	Custom fetch for mocking

Reconciliation

Export	Description
`snapline(live, expected, options)`	Full pipeline
`assertAgainstFile(live, path, options)`	Compare live data vs JSON file
`loadJsonFile(path, rootDir?)`	Load JSON with optional path sandboxing

Snapline options

Option	Type	Description
`ignoreFields`	`string[]`	Fields to strip before compare (dot paths)
`transformations`	`Record<string, fn>`	Normalize live values per field
`dataMapping`	`Record<string, map\|fn>`	Map codes across systems

API factories

import { api } from '@vaagatech/snapline-core';

api.rest({ endpoint, method, inputFile, body, headers })
api.graphql({ endpoint, query, queryFile, variables, variablesFile, dataPath })
api.soap({ endpoint, soapAction, envelope, inputFile, headers })

Database connection contract

Published packages do not ship SQL drivers. Implement DbConnectionLike with your Postgres/MySQL client:

import type { DbConnectionLike } from '@vaagatech/snapline-core';

/** async query(sql, params?) → DbRow[] */
const appDb: DbConnectionLike = {
  async query(sql, params) {
    // your pg/mysql driver here
    return rows;
  },
};

Demos use @vaagatech/snapline-demo-shared for SQLite and in-memory stubs (createSqliteConnection, seedDb, db.postgres/mysql/sqlite). See packages/core/examples/in-memory-db.mjs for a minimal stub you can copy.

Queue & async polling

Install @vaagatech/snapline-messaging-adapters for queue publishers. Core provides polling and comparison:

Export	Description
`runPublishAndPoll(config)`	Publish message, wait for async result, compare
`createDbAsyncResultResolver(config)`	Poll SQL until rows match `until` predicate
`createFileAsyncResultResolver(config)`	Poll `{correlationId}.json` on disk
`createMessageAsyncResultResolver(config)`	Wait on response topic via `MessageConsumerLike`
`waitForResult(check, options)`	Generic poll-until-ready helper

import { messaging } from '@vaagatech/snapline-messaging-adapters';
import { testSuite } from '@vaagatech/snapline-core';

const { publisher } = messaging.memory();

await testSuite('Order pipeline', {
  publishAndPoll: {
    publish: { publisher, topic: 'orders.request', payload: { orderId: 'ORD-1' } },
    poll: {
      db: {
        db: appDb,
        query: 'SELECT status FROM orders WHERE correlationId = :correlationId',
        until: (rows) => rows[0]?.status === 'PROCESSED',
      },
    },
    expected: { status: 'PROCESSED' },
    pollOptions: { timeoutMs: 30_000 },
  },
});

Poll targets: { db }, { file: { directory } }, { message: { consumer, topic } }, or { resolver }.

Warehouse comparison

import { runWarehouseComparison, nosql, createStreamReportWriter } from '@vaagatech/snapline-core';

await runWarehouseComparison({
  sourceDb,                    // DbConnectionLike — your SQL warehouse
  targetStore: nosql.memory(), // DocumentStoreLike — e.g. MongoDB adapter
  tables: [/* WarehouseTableSpec[] */],
  chunkSize: 50,
  report: { outputPath: './reports/warehouse.jsonl' },
});

createStreamReportWriter appends JSONL events without holding the full dataset in memory.

NoSQL

import { nosql } from '@vaagatech/snapline-core';

const store = nosql.memory();
nosql.seed(store, collection, documents);

Reporting

Export	Description
`resolveReportConfig(options)`	Parse CLI args and env vars
`writeTestReport(suites, config, meta?)`	Write JSON, HTML, or text report
`pushTestReportToHub(report, { hubUrl, project, tags })`	Push report to Snapline Hub
`resolveHubConfig(options)`	Parse `SNAPLINE_HUB_URL` / `--hub-url`
`redactFields(data, fields)`	Mask sensitive fields in report data
`redactSuiteResults(suites, fields)`	Redact all step results in suites

Environment variables:

REPORT_FORMAT — json, html, or text
REPORT_OUTPUT — output file path
REPORT_REDACT_FIELDS — comma-separated field paths

Fixture utilities

import { fixturesDir, moduleDir, DEFAULT_FIXTURE_LAYOUT } from '@vaagatech/snapline-core';

fixturesDir(import.meta.url, { relativePath: '../fixtures' })
moduleDir(import.meta.url)

`case.json` fields

Field	Description
`name`	Display name
`expectMatch`	`true` = expect match; `false` = expect mismatch
`expectStatus`	Expected HTTP status (default 200)
`skipAuth`	Skip auth headers for 401 tests
`failureType`	`dataMapping`, `transformation`, or `auth`
`expectedDiffPath`	Assert diff occurs at specific path

Package examples

Runnable examples ship in the repo under packages/*/examples/:

packages/core/examples/ — api-to-db, db-to-api, publish-and-poll-db, publish-and-poll-file
packages/messaging-adapters/ — in-memory and Kafka adapters
packages/snapline/examples/basic-snapline.mjs
packages/api-adapters/examples/ — rest, graphql, soap
packages/auth-adapters/examples/basic-auth.mjs