GitHub

Migration Guide

Probitas 2 runs on Bun and ships as a single probitas binary. Deno is no longer needed to run scenarios, and most scenarios run unchanged. This guide lists what does change when upgrading from Probitas 1.x.

Probitas 1.x keeps working if you are not ready to move, but it no longer receives updates. Pin it with:

  • PROBITAS_VERSION=1.0.0 for the shell installer
  • probitas-test/setup-probitas@v1 in GitHub Actions
  • github:probitas-test/probitas/v1.0.0 as the Nix flake input

Installation

The binary is downloaded from the GitHub Release; nothing else is required.

curl -fsSL https://raw.githubusercontent.com/probitas-test/probitas/main/install.sh | sh
  • The binary is installed to ~/.local/bin by default (1.x used ~/.deno/bin). PROBITAS_INSTALL_DIR still names the installation root, and the binary goes to $PROBITAS_INSTALL_DIR/bin.
  • Supported platforms are macOS (arm64, x64), Linux with glibc (x64, arm64), and Windows (x64, download the .zip from the release). musl-based Linux such as Alpine is not supported yet.
  • Homebrew (brew install probitas-test/tap/probitas) and probitas-test/setup-probitas@v2 install the binary as well.
  • The flake's overlays.default and packages.default keep providing probitas, built from the flake's revision as in 1.x (now a single binary instead of the sources run with Deno). Pin a release tag (v2.0.2 or later) for a released version.

See Installation for every method.

Scenarios

Probitas Imports Keep Working

Scenarios run against the copy of Probitas embedded in the binary, so they need no install step. The 1.x specifiers still resolve:

import { client, expect, scenario } from "jsr:@probitas/probitas@^0"; // still works

The 2.x name is the npm package, which also gives you editor support (see Editor Support):

import { client, expect, scenario } from "@probitas-test/probitas";

Other Dependencies Need a package.json

Only Probitas itself is embedded. Third-party modules must be installed next to your scenarios and imported by their bare name; npm: and jsr: specifiers for other packages are not resolved.

1.x2.x
import ms from "npm:ms@2"npm install ms, then import ms from "ms"
import { assertEquals } from "jsr:@std/assert"npx jsr add @std/assert, then import ... from "@std/assert"

No Deno Global

Scenarios run on Bun, so Deno.* APIs are unavailable. Use the Node.js equivalents, which Bun implements:

1.x2.x
Deno.env.get("API_URL")process.env.API_URL
Deno.readTextFile(path)readFile(path, "utf8") from node:fs/promises
Deno.connect({ port })createConnection({ port }) from node:net
Deno.cwd()process.cwd()

To type-check code that uses these APIs, add the Node.js type definitions (see Editor Support).

Removed: Deno KV Client

client.deno_kv (and @probitas/client-deno-kv) is gone, along with its expectations, since Deno KV only exists inside the Deno runtime.

Editor Support

1.x relied on the Deno language server. In 2.x, run probitas init (or copy what it generates into an existing project): it writes a package.json that pins @probitas-test/probitas to the binary's version and a tsconfig.json. Install with your package manager (npm install, bun install, ...) and any TypeScript-aware editor provides completion, type checking, and hover documentation.

probitas init
cd probitas
npm install

Scenarios that use Node.js APIs (process.env, node:fs/promises, Buffer, ...) also need @types/node in package.json and "types": ["node"] in tsconfig.json; without them, probitas check and your editor report process and friends as unknown. Only the @types packages listed in types are loaded. Depending on the Probitas version, probitas init may already have added both; otherwise add them yourself:

npm install --save-dev @types/node

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Commands

1.x2.x
probitas fmtUnchanged output (the deno fmt formatter is built in); adds --check
probitas lintLints with Biome's recommended rules instead of deno lint's
probitas checkType-checks with the checker built into the binary (bun check)
probitas cacheNow probitas cache duckdb: pre-fetches the DuckDB native binding
--deno-*, -r/--reloadRemoved

run, list, and init keep their options, and configuration files (probitas.json, probitas.jsonc) are unchanged.

lint reports different rules than deno lint; silence a finding with // biome-ignore lint/<group>/<rule>: <reason>. check resolves @probitas-test/probitas from the project, so install the package.json that probitas init writes first. Scenarios still importing jsr:@probitas/probitas run, but do not type-check until they import @probitas-test/probitas.

See Code Quality Commands for details.

DuckDB

The DuckDB native binding is not embedded (it would add about 110MB). The first scenario that creates a DuckDB client downloads it from the npm registry, verifies it, and caches it per version and platform. For CI images or offline machines, run probitas cache duckdb ahead of time, or point PROBITAS_DUCKDB_DIR at an extracted binding.

See Native Dependencies for details.

Search Documentation