Architecture

Snapline is an npm monorepo. Consumers install one package; maintainers split concerns across five published libraries plus a private demo workspace.

Package layers

┌─────────────────────────────────────────────────────────────┐ │ @vaagatech/snapline-core (entry point) │ │ testSuite · fixture runners · DB/NoSQL · publishAndPoll │ └───────┬─────────────────┬───────────────────┬───────────────┘ │ │ │ ┌───────▼────────┐ ┌──────▼──────────┐ ┌──────▼────────────────┐ │ snapline-engine│ │ api-adapters │ │ messaging-adapters │ │ compare pipeline│ │ REST·GraphQL·SOAP│ │ Kafka · in-memory │ └────────────────┘ └────────┬────────┘ └─────────────────────────┘ │ ┌─────────▼──────────┐ │ auth-adapters │ │ OAuth2·OpenID·Basic│ └────────────────────┘
PackageResponsibilityKey exports
@vaagatech/snapline-core Orchestration — wires auth, HTTP, DB, fixtures, reports testSuite, runApiFixtureCases, runDbComparison, runWarehouseComparison, DbConnectionLike, writeTestReport
@vaagatech/snapline-engine Pure reconciliation — no I/O snapline, assertAgainstFile
@vaagatech/snapline-api-adapters Protocol executors with SSRF guards and timeouts executeApi, api.rest, api.graphql, api.soap
@vaagatech/snapline-auth-adapters Token acquisition for API calls auth.oauth2, auth.openid, auth.basic
@vaagatech/snapline-messaging-adapters Queue publish/consume — Kafka, in-memory, custom messaging.memory, messaging.kafkaPublisher, publishMessage

Snapline Hub (optional)

Snapline Hub is a separate, optional reporting UI that stores and visualizes TestRunReport data. It is not part of the npm packages — use it when you want a centralized dashboard for test run history. Push reports via pushTestReportToHub() or SNAPLINE_HUB_URL. The Python edition has equivalent push_test_report_to_hub().

Runtime flow — testSuite

testSuite(name, config) │ ├─ auth.initialize() optional OAuth2 / OpenID / Basic │ ├─ api executeApi → snapline vs expectedFile ├─ dbComparison fetch source + target rows → snapline ├─ apiToDb executeApi → fetch DB row → snapline ├─ dbToApi fetch DB row → executeApi → snapline └─ publishAndPoll publish queue → poll DB / file / topic → snapline │ ▼ snapline(live, expected, { ignoreFields, transformations, dataMapping }) │ ▼ { match, diff, processed, expected } → TestSuiteResult

Fixture case runners

Two runners live in core for data-driven scenarios:

Each case directory contains case.json (metadata) plus protocol-specific files. Path sandboxing ensures fixture paths cannot escape the fixtures root.

Repository layout (maintainers)

snapline/
├── packages/
│   ├── core/           @vaagatech/snapline-core
│   ├── snapline/       @vaagatech/snapline-engine
│   ├── api-adapters/   @vaagatech/snapline-api-adapters
│   ├── auth-adapters/  @vaagatech/snapline-auth-adapters
│   └── messaging-adapters/  @vaagatech/snapline-messaging-adapters
└── demo/               private — mock server + 21 scenarios
    ├── shared/         @vaagatech/snapline-demo-shared (mock API + SQLite)
    ├── scenarios/      one package per scenario
    └── run-all/        runs all 21 sequentially

Published package dependencies

@vaagatech/snapline-core has zero external runtime dependencies. It exports the DbConnectionLike interface for SQL — you bring your own Postgres/MySQL driver. SQLite and stub DB helpers live in @vaagatech/snapline-demo-shared (demo only, not published to npm consumers as a required dependency).

Security & reliability