KrepkoJS

Contract-driven HTTP testing library for executable flows.

KrepkoJS is not a unit testing framework. It's not classic E2E. It's a contract system that protects the logic between client and server using executable flows.

Why KrepkoJS?

- Contract-first: Tests describe real HTTP user flows as contracts
- CI-friendly: If a contract breaks, CI fails. No silent regressions.
- Simple DSL: Readable by both humans and AI agents
- Draft mode: Mark work-in-progress flows without breaking CI
- Zero magic: Minimal, explicit, predictable

Installation

``bash
npm install krepko
`

Quick Start

Create a file auth.krepko.ts:

`typescript
import { krepko, expect } from 'krepko';

krepko('https://api.example.com')
.flow('User Authentication')
.tags(['smoke', 'auth'])
.do('Register user', async (ctx) => {
const res = await ctx.post('/users', {
email: 'test@example.com',
password: 'secret123',
});

res.expectStatus(201);
res.expectBody({ email: 'test@example.com' });

ctx.set('userId', res.body.id);
})
.do('Login', async (ctx) => {
const res = await ctx.post('/auth/login', {
email: 'test@example.com',
password: 'secret123',
});

res.expectStatus(200);
res.expectBody({ token: expect.string });

ctx.bearer(res.body.token);
})
.do('Get profile', async (ctx) => {
const res = await ctx.get('/users/me');

res.expectStatus(200);
res.expectBody({ id: ctx.getVar('userId') });
});
`

Run:

`bash
npx krepko --pattern "*/.krepko.ts"
`

Output:

`
KrepkoJS v0.1.0
Base URL: https://api.example.com

Flow: User Authentication
✓ Register user 132ms
✓ Login 81ms
✓ Get profile 45ms

Summary:
✓ 1 flow passed
Total: 1 flow (3 steps)
Time: 0.26s

✓ Krepko держит ваш API
`

API

$3

Creates a new Krepko instance with the specified base URL.

`typescript
krepko('https://api.example.com')
`

$3

Defines a new flow (test scenario).

`typescript
krepko(url).flow('User Registration')
`

$3

Adds a step to the flow. Steps execute sequentially.

`typescript
.do('Create user', async (ctx) => {
// your code here
})
`

$3

Adds tags for filtering flows.

`typescript
.flow('Auth').tags(['smoke', 'auth'])
`

$3

Marks flow as draft. Draft failures don't fail CI in dev or ci mode.

`typescript
.flow('Experimental').isDraft('Work in progress')
`

Context (ctx)

$3

`typescript
ctx.get(path, headers?)
ctx.post(path, body?, headers?)
ctx.put(path, body?, headers?)
ctx.patch(path, body?, headers?)
ctx.delete(path, headers?)
`

$3

`typescript
ctx.set('key', value) // Store value
ctx.getVar('key') // Retrieve value
ctx.vars // Get all stored values
`

$3

`typescript
ctx.bearer(token) // Set Bearer token for subsequent requests
ctx.clearAuth() // Clear authentication
`

Response Assertions

$3

`typescript
res.expectStatus(200)
res.expectStatus(201)
`

$3

Partial matching - only checks specified fields:

`typescript
res.expectBody({ id: 1, status: 'active' })
`

$3

Use matchers for flexible assertions:

`typescript
import { expect } from 'krepko';

res.expectBody({
token: expect.any, // Field exists (any value)
id: expect.number, // Is a number
name: expect.string, // Is a string
active: expect.boolean, // Is a boolean
tags: expect.array, // Is an array
meta: expect.object, // Is an object
role: 'admin', // Exact value
})
`

CLI

`bash
npx krepko [options]
`

$3

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| --pattern | -p | Glob pattern for flow files | */.krepko.ts |
| --mode | -m | Run mode: dev, ci, strict | ci |
| --tags | -t | Filter by tags (comma-separated) | - |
| --help | -h | Show help | - |

$3

- dev: Draft failures shown as warnings, exit 0
- ci: Draft failures shown as warnings, exit 0. Non-draft failures exit 1
- strict: Any draft or failure exits 1

$3

`bash


Run all flows

npx krepko

Run specific pattern

npx krepko --pattern "flows/*/.krepko.ts"

Filter by tags

npx krepko --tags smoke
npx krepko --tags smoke,auth

Strict mode (drafts fail CI)

npx krepko --mode strict
`

$3

`bash
KREPKO_MODE=ci # Default mode
`

Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All non-draft flows passed |
| 1 | At least one non-draft flow failed (or draft in strict mode) |

Best Practices

$3

`
flows/
auth.krepko.ts
users.krepko.ts
payments.krepko.ts
`

$3

`typescript
.flow('Critical payment flow')
.tags(['smoke', 'payments', 'critical'])
`

$3

`typescript
.flow('New checkout v2')
.isDraft('Waiting for backend deploy')
`

$3

`typescript
.do('Create order', async (ctx) => {
const res = await ctx.post('/orders', { item: 'book' });
ctx.set('orderId', res.body.id);
})
.do('Get order', async (ctx) => {
const res = await ctx.get(/orders/${ctx.getVar('orderId')});
res.expectStatus(200);
})
`

TypeScript

KrepkoJS is written in TypeScript and provides full type definitions.

`typescript
import { krepko, expect, Context, KrepkoResponse } from 'krepko';
``

Requirements

- Node.js >= 18.0.0

License

MIT