Get started on your computer

In this tutorial we’ll install Varar into a project, configure it, run a first oath, and then deliberately break it. By the end you will have seen an oath pass and fail as a test on your own machine.

Pick your preferred programming language in the language selector in the top-right corner of the page. Every command and code sample below follows that choice.

Before you start

You need your language’s toolchain already installed — Varar adds a library and a test-framework adapter to a project you can already build and test.

TypeScript

Node.js 22.18 or newer. Node strips TypeScript types by itself from 22.18 on. Older versions fail the run with 'Unknown file extension ".ts"', and need NODE_OPTIONS=--experimental-strip-types.

Java

JDK 21 or newer, with Maven or Gradle. The published artifacts target Java 21.

Kotlin

JDK 21 or newer, with Gradle and Kotlin 2.x. The published artifacts target Java 21.

Python

Python 3.11 or newer. The commands below use uv; pip and poetry work the same way.

Ruby

Ruby 3.2 or newer, with Bundler.

Rust

Rust 1.85 or newer, installed with rustup. The crates are edition 2024, which 1.85 is the first release to support.

C#

The .NET 10 SDK or newer. The packages target net10.0.

Go

Go 1.26 or newer.

1. Install

   TypeScript

   pnpm add -D @varar/varar @varar/cli

   Java

   <!-- pom.xml — use the latest release from Maven Central -->
   <dependency>
     <groupId>dev.varar</groupId>
     <artifactId>junit</artifactId>
     <version>0.8.0</version>
     <scope>test</scope>
   </dependency>

   Kotlin

   // build.gradle.kts — use the latest release from Maven Central
   testImplementation("dev.varar:kotlin:0.8.0")
   testImplementation("dev.varar:junit:0.8.0")

   Python

   uv add --dev pytest-varar

   Ruby

   bundle add varar-rspec

   Rust

   cargo add varar-cargotest --dev

   C#

   dotnet add package Varar.TestAdapter

   Go

   go get github.com/varar-dev/varar/go

   This adds Varar’s author API (the package your step definitions import) and the adapter that runs oaths in your test framework.

2. Configure

   Varar is configured by one file, varar.config.json — the single source of truth for which Markdown files are oaths and which files bind their steps. Ports with a varar CLI scaffold it (and a working example) in one command; on the others you create it by hand.

   TypeScript

   pnpm exec varar init

   One command writes the config and a working example oath:

   created varar.config.json
   created varar/deep-thought.md
   created src/varar/deep-thought.steps.ts
   updated package.json (added "type": "module")

   varar.config.json decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["src/varar/**/*.steps.ts"]
   }

   Java

   The Java port has no varar init yet, so configuration is two small files you create by hand. varar.config.json decides which Markdown files are oaths — and lists step classes by package wildcard instead of a file glob: varar.* means every step class in the varar package:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["varar.*"]
   }

   A one-line JUnit suite makes Maven or Gradle discover the oaths:

   src/test/java/varar/RunVararTest.java

   package varar;
   
   import org.junit.platform.suite.api.IncludeEngines;
   import org.junit.platform.suite.api.SelectDirectories;
   import org.junit.platform.suite.api.Suite;
   
   @Suite @IncludeEngines("varar") @SelectDirectories(".") public class RunVararTest {}

   The Maven and Gradle sample projects are complete, runnable copies you can start from.

   Kotlin

   The Kotlin port has no varar init yet, so configuration is two small files you create by hand. varar.config.json decides which Markdown files are oaths — and lists step classes by package wildcard instead of a file glob: varar.* means every step class in the varar package:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["varar.*"]
   }

   A one-line JUnit suite makes Maven or Gradle discover the oaths:

   src/test/kotlin/varar/RunVararTest.kt

   package varar
   
   import org.junit.platform.suite.api.IncludeEngines
   import org.junit.platform.suite.api.SelectDirectories
   import org.junit.platform.suite.api.Suite
   
   @Suite @IncludeEngines("varar") @SelectDirectories(".") class RunVararTest

   The Kotlin sample project is a complete, runnable copy you can start from.

   Python

   uv run varar init

   One command writes the config and a working example oath:

   created varar.config.json
   created varar/deep-thought.md
   created tests/varar/deep_thought.steps.py

   varar.config.json decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["tests/varar/**/*.steps.py"]
   }

   Ruby

   bundle exec varar init

   One command writes the config and a working example oath:

   created varar.config.json
   created varar/deep-thought.md
   created spec/varar/deep_thought.steps.rb
   created spec/varar_spec.rb

   (With varar-minitest installed instead of varar-rspec, the bridge lands in test/varar_test.rb and the steps in test/varar/.)

   varar.config.json decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["spec/varar/**/*.steps.rb"]
   }

   Rust

   The Rust port has no varar init yet, so create varar.config.json at the project root by hand. It decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["src/varar/*.steps.rs"]
   }

   A small tests/varar.rs harness hands the oaths to cargo test — copy it from the Rust sample project — a complete, runnable copy you can start from.

   C#

   The C# port has no varar init yet, so create varar.config.json at the project root by hand. It decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["steps/*.steps.cs"]
   }

   dotnet test discovers the oaths through the Varar.TestAdapter package — copy the project wiring from the C# sample project — a complete, runnable copy you can start from.

   Go

   The Go port has no varar init yet, so create varar.config.json at the project root by hand. It decides which Markdown files are oaths and which files bind their steps:

   varar.config.json

   {
     "docs": { "include": ["varar/**/*.md"], "exclude": [] },
     "steps": ["*.steps.go"]
   }

   A small varar_test.go harness hands the oaths to go test — copy it from the Go sample project — a complete, runnable copy you can start from.

3. A first oath

   The example oath is plain Markdown with one concrete example — varar init already wrote it for you; if your port has no CLI, create it now, in the varar/ directory your config’s docs globs match:

   varar/deep-thought.md

   # Deep Thought
   
   You're really not going to like it.
   
   The answer to the great question of life, the universe and everything is 42.
   
   It was a tough assignment.

   Notice there are no keywords and no special syntax — it’s ordinary Markdown prose. One sentence makes a checkable claim; Varar matches that phrase, and everything around it is just documentation for the reader.

   The steps file binds that sentence to code. A sensor reads the software and returns what it actually produced, for Varar to compare against the number in the Markdown:

   TypeScript

   src/varar/deep-thought.steps.ts

   import { steps } from '@varar/varar'
   
   const { sensor } = steps()
   
   sensor('life, the universe and everything is {int}', () => 42)

   Java

   src/test/java/varar/DeepThoughtSteps.java

   package varar;
   
   import dev.varar.State;
   import dev.varar.StepDefinitions;
   import dev.varar.Steps;
   
   public final class DeepThoughtSteps implements StepDefinitions<DeepThoughtSteps.Ctx> {
       record Ctx() implements State {}
   
       @Override
       public void register(Steps<Ctx> s) {
           s.state(Ctx::new);
           s.sensor("life, the universe and everything is {int}", (Ctx ctx, Integer answer) -> 42);
       }
   }

   Kotlin

   src/test/kotlin/varar/deep-thought.steps.kt

   @file:JvmName("DeepThoughtSteps")
   
   package varar
   
   import dev.varar.kotlin.sensor
   import dev.varar.kotlin.steps
   
   val deepThoughtSteps =
       steps {
           sensor("life, the universe and everything is {int}") { _: Int -> 42 }
       }

   Python

   tests/varar/deep_thought.steps.py

   from varar import steps
   
   param, stimulus, sensor = steps()
   
   
   @sensor("life, the universe and everything is {int}")
   def _(state, answer):
       return 42

   Ruby

   spec/varar/deep_thought.steps.rb

   require 'varar'
   
   steps do
     sensor('life, the universe and everything is {int}') { 42 }
   end

   Rust

   src/varar/deep_thought.steps.rs

   use varar::Steps;
   
   pub fn register(s: &mut Steps<()>) {
       s.sensor("life, the universe and everything is {int}", |_ctx: (), _answer: i64| Ok(42));
   }

   C#

   steps/deep-thought.steps.cs

   using Varar;
   using Varar.Core;
   
   namespace Examples;
   
   public static class DeepThoughtSteps
   {
       public static void Register(Steps s)
       {
           s.Sensor("life, the universe and everything is {int}", (state, answer) => Value.Of(42));
       }
   }

   Go

   deep_thought.steps.go

   package examples
   
   import "github.com/varar-dev/varar/go/varar"
   
   func Register(s *varar.Steps) {
     s.Sensor("life, the universe and everything is {int}", func(state varar.Value, args []varar.Value) (*varar.Value, error) {
       return varar.Ptr(varar.IntValue(42)), nil
     })
   }

4. Run it

   TypeScript

   pnpm vitest run

   Java

   mvn test

   Kotlin

   ./gradlew test

   Python

   uv run pytest

   Ruby

   bundle exec rspec

   Rust

   cargo test

   C#

   dotnet test

   Go

   go test

   Varar reports one example passing:

   varar/deep-thought.md
     ✓ Deep Thought
   
   1 example, 1 passed, 0 failed

   pytest, RSpec, JUnit, cargo test, dotnet test and go test each report the same example passing in their own format. The Markdown file just ran as a test, and the software kept its word.

5. Watch it fail on purpose

   Never trust a test you haven’t seen fail. Open the steps file and change the answer the sensor returns from 42 to 43:

   TypeScript

   sensor('life, the universe and everything is {int}', () => 43)

   Java

   s.sensor("life, the universe and everything is {int}", (Ctx ctx, Integer answer) -> 43);

   Kotlin

   sensor("life, the universe and everything is {int}") { _: Int -> 43 }

   Python

   @sensor("life, the universe and everything is {int}")
   def _(state, answer):
       return 43

   Ruby

   sensor('life, the universe and everything is {int}') { 43 }

   Rust

   s.sensor(
       "life, the universe and everything is {int}",
       file!(),
       line!() as usize,
       Handler::sync1(|_state, _answer| Ok(Some(Value::Int(43)))),
   );

   C#

   s.Sensor("life, the universe and everything is {int}", (state, answer) => Value.Of(43));

   Go

   s.Sensor("life, the universe and everything is {int}", func(state varar.Value, args []varar.Value) (*varar.Value, error) {
     return varar.Ptr(varar.IntValue(43)), nil
   })

   Run Varar again. The example now fails: the oath still says 42, but the sensor observed 43. The output shows both values and points at the exact 42 in the Markdown where the promise broke.

   Revert the change and run once more — one example, one passed. You have seen both sides of the contract.

Next

• Your first oath from scratch — write your own oath in a blank Markdown file and bind its steps.
• Already have a vitest suite? Run oaths through vitest instead of the CLI.