Getting Started

1. Create your project

mkdir my-app-integration-tests && cd my-app-integration-tests
npm init -y
npm install @vaagatech/snapline-core

Add "type": "module" to package.json (or use .mjs files).

2. Project layout

my-app-integration-tests/
├── fixtures/
│   ├── input.json          # request body (REST POST)
│   └── expected.json       # golden snapshot
├── tests/
│   └── user-sync.test.mjs
├── .env                    # API_BASE_URL, CLIENT_ID, CLIENT_SECRET
└── package.json

3. Add fixtures

fixtures/input.json

{ "email": "alice@example.com" }

fixtures/expected.json — use placeholders for fields you will normalize:

{
  "email": "alice@example.com",
  "status": "synced",
  "currentdate": "VALID_DATE"
}

4. Write your first test

tests/user-sync.test.mjs

import { testSuite, auth } from '@vaagatech/snapline-core';

const baseUrl = process.env.API_BASE_URL ?? 'https://your-api.com';

const result = await testSuite('User sync — API vs fixture', {
  auth: auth.oauth2({
    tokenUrl: `${baseUrl}/oauth/token`,
    clientId: process.env.CLIENT_ID,
    clientSecret: process.env.CLIENT_SECRET,
  }),
  baseUrl,
  api: {
    endpoint: '/api/v1/user/sync',
    method: 'POST',
    inputFile: './fixtures/input.json',
    expectedFile: './fixtures/expected.json',
    ignoreFields: ['pincode'],
    transformations: {
      currentdate: (v) =>
        typeof v === 'string' && !Number.isNaN(Date.parse(v))
          ? 'VALID_DATE'
          : 'INVALID_DATE',
    },
  },
});

process.exitCode = result.passed ? 0 : 1;

5. Run it

API_BASE_URL=https://staging.your-api.com \
CLIENT_ID=... CLIENT_SECRET=... \
node tests/user-sync.test.mjs

On success:

▶ User sync — API vs fixture
  ✓ auth initialized
  ✓ api response matched fixture file
✅ User sync — API vs fixture: PASSED

On failure you get a structured diff with field paths and actual vs expected values.

Try the repo demo (optional)

The Snapline monorepo includes 21 runnable scenarios with a local mock API and demo SQLite databases (@vaagatech/snapline-demo-shared):

git clone https://github.com/vaagatech/snapline.git
cd snapline
npm install
npm run demo          # build + run all 21 scenarios
npm run demo:list     # list scenario ids
npm run demo:run -- api-vs-file-graphql

Run from this repo (maintainers)

npm install
npm run build
npm run typecheck
npm run demo