Installation

Requirements

Requirement	Why
Node 24+	The host process. Argus uses node:util.parseArgs, fs.promises.glob and util.styleText. Declared as "engines": { "node": ">=24" }.
A react-native install	Argus reads the Hermes engine your project pins from it. Without one, you must name a binary yourself.
macOS or Linux	Prebuilt Hermes binaries are published for darwin-arm64, darwin-x64, linux-x64 and linux-arm64. Windows is not supported.
Sometimes git, cmake, ninja	Only when no prebuilt applies to your React Native version — see below.

You never need Xcode, Android Studio, a simulator, or Metro.

Whether you need a compiler toolchain depends on which React Native you are on, because a prebuilt has to exist for the exact Hermes version your project pins:

Your React Native	First run
0.86, 0.87	Downloads a prebuilt. Nothing else to install
0.83, 0.84, 0.85	No release cut yet → --provision, which needs git, cmake, ninja
0.78 – 0.82	macOS: uses the VM inside react-native, free. Linux: --provision

Linux needs glibc 2.38 today

The published Linux archives are glibc builds that currently require glibc 2.38, so they do not start on Ubuntu 22.04 LTS (2.35), Debian 12 (2.36), Amazon Linux 2023 or RHEL 9 (2.34) — the loader rejects them before any Argus code runs. Ubuntu 24.04+, Debian 13 and Fedora 39+ are fine.

The build has since moved to the oldest supported runner, with a CI gate that reads the requirement out of the ELF and fails above glibc 2.35. That has not shipped yet — it landed after the current release was cut. Until the archives are rebuilt, use --provision or --hermes on those distributions.

Alpine and other musl distributions cannot run these binaries at all, now or after the rebuild. A glibc build does not run on musl; that is not a packaging choice.

Install

pnpm

pnpm add -D @arguslab/argus

npm

npm install --save-dev @arguslab/argus

yarn

yarn add -D @arguslab/argus

One package, one binary — 30 files, 68 kB packed, 300 kB installed. Everything the runner needs on the host comes with it: the bundler, the Hermes adapter, the source-map remapper, the reporter.

Note

There is no @arguslab/cli, @arguslab/rntl or @arguslab/core on npm, and there never will be. Those are internal seams inside the repository — see Package map.

Component testing (optional)

Testing React components needs React and a renderer. Plain TypeScript and plain-logic tests do not.

pnpm

pnpm add -D react test-renderer

npm

npm install --save-dev react test-renderer

yarn

yarn add -D react test-renderer

Both are optional peer dependencies, so installing Argus does not pull them in. A suite that never imports argus never pulls React into the bundle, so a pure-TypeScript project runs with neither installed.

Import argus without them and the run stops at the bundle step:

✘ [ERROR] Could not resolve "react"
✗ INFRASTRUCTURE FAILURE [bundle] Build failed with 5 errors

Exit code 2 — an infrastructure failure, never a red test. See Component testing.

TypeScript

Test globals (describe, test, expect) and the virtual argus module are declared in the package, but TypeScript will not find them on its own: it only auto-loads ambient declarations from node_modules/@types/*, and Argus is not published under that scope.

Point it at them once — either in tsconfig.json:

tsconfig.json

{ "compilerOptions": { "types": ["@arguslab/argus"] } }

or, leaving compilerOptions alone, with one line in a .d.ts your include already covers:

argus-env.d.ts

/// <reference types="@arguslab/argus" />

Caution

This step is not optional. Skip it and you get Cannot find name 'describe' and Cannot find module 'argus' from tsc. It affects type-checking only — the run itself works either way, because the bundler never consults your tsconfig.

Add a script

package.json

{
  "scripts": {
    "test:hermes": "argus \"src/**/*.test.ts\" \"src/**/*.test.tsx\""
  }
}

Quote your globs. Leaving them unquoted lets the shell expand them before Argus sees them, which usually works and occasionally does something surprising with **.

Or put it in a config file

Anything you would otherwise repeat on the command line can live in an optional argus.config.ts at the project root:

argus.config.ts

import { defineConfig } from '@arguslab/argus';

export default defineConfig({
  include: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
  timeout: 30000,
});

package.json

{
  "scripts": {
    "test:hermes": "argus"
  }
}

No transpiler and no extra dependency — Node strips the types itself. Because root defaults to the config file’s own directory, argus then behaves identically whether you run it from the repo root or from a subdirectory.

Note

This works whatever your package.json says, including the "type": "commonjs" that npm init -y writes. Node reads a .ts file in such a package as a CommonJS script, where the import above would be a syntax error; Argus reloads it as the module it is, after the CommonJS reading has already failed to parse — so a config written as module.exports still loads as CommonJS, and either way the file runs exactly once. See Configuration.

Every option, the search order, and precedence against flags: Configuration.

First run

pnpm test:hermes

On the first run Argus resolves which Hermes your project pins and finds a binary for it. On React Native 0.86 and 0.87 that means downloading the matching prebuilt, verifying its SHA-256, and caching it under ~/.argus/cache/; later runs reuse the cache and start immediately. On other versions it uses the VM bundled inside react-native, or tells you to pass --provision — see How the binary is provisioned.

The run opens with one line naming exactly what it ran on:

✓ hermes v1 hermes-v250829098.0.16 · prebuilt darwin-arm64 · /Users/you/.argus/cache/hermes-hermes-v250829098.0.16/build/bin/hermes

Tip

That line is deliberately one line so it survives in a CI log. The engine identity is the difference between a meaningful run and a misleading one — read it.

Using a Hermes binary you already have

Any of these skips provisioning entirely:

argus --hermes /path/to/hermes "src/**/*.test.ts"

ARGUS_HERMES=/path/to/hermes argus "src/**/*.test.ts"

Or drop one at ./.hermes/hermes in your project and it is picked up with no flag at all.

Full precedence rules: How the binary is provisioned.

Building Hermes from source

When no prebuilt applies — a React Native version whose Hermes pin is date-based or a bare commit SHA, or one of the releases not yet cut — Argus can build the VM. It never does so silently:

argus --provision "src/**/*.test.ts"

Needs git, cmake and ninja on PATH. Expect a couple of minutes for the first build; the result is cached like any other binary.

Caution

This is not a Windows escape hatch. Windows has no published prebuilt and no verified source-build path — it is unsupported, not merely inconvenient.

CI

.github/workflows/test.yml

- uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'pnpm'

- run: pnpm install --frozen-lockfile

# Cache the provisioned VM so only the first run pays the download.
- uses: actions/cache@v4
  with:
    path: ~/.argus/cache
    key: argus-hermes-${{ runner.os }}-${{ runner.arch }}

- run: pnpm test:hermes

Argus never prompts. A blocked provisioning step fails with a message listing every source it tried and what to type next — a prompt in CI is a hang.