Getting Started

Install

TypeScript

npm install --save-dev @averspec/core vitest

Aver uses Vitest as its test runner.

Python

pip install averspec

Aver uses pytest as its test runner.

Ruby

# RubyGems publish coming soon — install from source:
git clone https://github.com/averspec/aver-rb.git
cd aver-rb && bundle install

Aver uses RSpec as its test runner.

Go

go get github.com/averspec/aver-go

Aver uses Go’s built-in testing package.

Rust

# crates.io publish coming soon — install from git:
# Cargo.toml: averspec = { git = "https://github.com/averspec/aver-rs" }

Aver uses Rust’s built-in test framework.

Kotlin

// Maven Central publish coming soon — build from source:
// git clone https://github.com/averspec/aver-jvm.git
// ./gradlew publishToMavenLocal
// build.gradle.kts:
testImplementation("dev.averspec:averspec:0.1.0")

Aver uses JUnit 5 as its test runner.

The 30-second version

TypeScript

npx aver init
npx aver run

Python

aver init
aver run

Ruby

aver init
aver run

Go

# Define domain, adapter, and test in Go files
go test ./...

Rust

# Define domain, adapter, and test in Rust files
cargo test

Kotlin

./gradlew test

That scaffolds a domain, a unit adapter, and a test — then runs it. You’ll see output like:

 ✓ create a task in backlog [unit]
 ✓ move task through workflow [unit]

From here, replace the stubs with your real domain. The rest of this page explains the pieces and helps you choose the right starting path.

Where are you starting from?

Your entry point depends on what you have today.

I have existing code with no tests

Start by locking in what exists. Install the approvals package and capture current behavior before changing anything:

npm install --save-dev @averspec/approvals

import { test } from 'vitest'
import { approve } from '@averspec/approvals'
import { processOrder } from '../src/orders.js'

test('order processing output', async () => {
  const result = processOrder({ items: [{ sku: 'W-100', qty: 3 }] })
  await approve(result)
})

Run npx aver approve to create baselines, then npx aver run to verify against them. Baselines are stored in __approvals__/ next to your test file — commit them to source control. You now have a safety net.

approve() is also exported as characterize() if that reads better for your characterization tests.

From here, extract a domain vocabulary as patterns emerge. The tutorial walks through this process end-to-end with a complete example.

I have existing code with tests I want to restructure

If you already have tests but they’re scattered across page objects, test helpers, and ad-hoc abstractions, Aver gives you a spine to consolidate them.

Look at your existing test helpers. They probably already encode domain operations — createUser(), loginAs(), verifyOrderStatus(). Those are your domain vocabulary candidates. Define them as a domain, write adapters that delegate to your existing infrastructure, and your old tests become acceptance tests.

Start with the tutorial to see the pattern, then apply it to your own test helpers.

I’m building something new

Scaffold a project:

TypeScript

npx aver init

This generates:

• domains/task-board.ts — starter domain with actions and assertions
• adapters/task-board.unit.ts — unit adapter with handler stubs
• tests/task-board.spec.ts — example test
• aver.config.ts — adapter registration

Python

aver init

This generates:

• domains/task_board.py — starter domain with actions and assertions
• adapters/task_board_unit.py — unit adapter with handler stubs
• tests/test_task_board.py — example test
• aver_config.py — adapter registration

Ruby

aver init

This generates:

• domains/task_board.rb — starter domain with actions and assertions
• adapters/task_board_unit.rb — unit adapter with handler stubs
• spec/task_board_spec.rb — example test

Go

// domains/taskboard.go — define domain struct with marker fields
// adapters/taskboard_unit.go — implement handlers
// taskboard_test.go — write tests

Rust

// src/domains/task_board.rs — define domain with markers
// src/adapters/task_board_unit.rs — implement handlers
// tests/task_board.rs — write tests

Kotlin

// src/test/kotlin/domains/TaskBoard.kt — define domain
// src/test/kotlin/adapters/TaskBoardUnit.kt — implement handlers
// src/test/kotlin/tests/TaskBoardTest.kt — write tests

Run the tests to verify the scaffold works, then replace the stubs with your real domain.

For greenfield projects, consider starting with an Example Mapping session to discover your domain vocabulary before writing code.

The pieces

Regardless of starting point, every Aver project has four pieces:

domains/          # What — vocabulary in business language
adapters/         # How — binds vocabulary to implementations
tests/            # Verify — scenarios using domain language
aver.config.*     # Wiring — registers adapters

Domain — declares actions (do something), queries (read something), and assertions (check something). No implementation details. See API Reference.

Adapter — implements every domain operation for a specific protocol. The unit protocol calls your code’s public interfaces directly. http and playwright are separate packages. The type system enforces that every domain operation has a handler — miss one and you get a compile error.

Tests — import the domain, never the adapter. suite(domain) gives you a typed test function. Tests use given/when/then (or act/query/assert) to compose domain operations into scenarios.

Config — registers adapters. When multiple adapters are registered for the same domain, every test runs against all of them automatically.

Configure your test runner

TypeScript

Create or update vitest.config.ts to load the Aver config:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['./aver.config.ts'],
  },
})

Python

Aver auto-discovers aver_config.py via pytest plugin. No extra configuration needed.

Ruby

Require Aver in your spec_helper.rb:

require 'averspec'

Go

Import the adapter in your test file:

import _ "yourproject/adapters"

Rust

Aver auto-discovers adapters via the test harness. No extra configuration needed.

Kotlin

Aver auto-discovers adapters via JUnit 5 service loader. No extra configuration needed.

When to add what

When you need…	Add…
A safety net for existing code	Approval testing — captures current behavior as a baseline
API-level testing	HTTP protocol adapter — runs tests against a real server
Browser testing	Playwright protocol adapter — drives real browser UI
Telemetry verification	Telemetry declarations on domain markers. See Telemetry Tutorial
AI-assisted workflow	Agent plugin (TypeScript only) — workflow skills + scenario pipeline. See AI-Assisted
CI integration	No extra packages — aver run in your pipeline. See CI Integration

You don’t need everything on day one. Start with the core package and a unit adapter. Add protocols as your needs grow.

Next steps

• Tutorial: Legacy Code — from untested code to multi-adapter tests
• Tutorial: Greenfield — build a domain from scratch
• Tutorial: Telemetry — verify observability contracts alongside behavior
• Multi-Adapter Testing — add HTTP and Playwright adapters
• Architecture — how the three-layer model works and why
• API Reference — domains, adapters, protocols, and suites