NAME¶

r2r — radare2 regression testsuite

SYNOPSIS¶

DESCRIPTION¶

r2r is a command-line regression testing framework for Radare2 and its third-party plugins.

It automates the discovery and execution of diverse test suites—including unit tests, JSON validations, fuzz tests, and architecture-specific checks—to ensure that code changes do not introduce regressions.

r2r supports parallel test execution, interactive failure handling, custom timeouts, and filtering of tests by type or name. It integrates seamlessly into continuous integration workflows or can be used locally, and requires only that Radare2 be installed and available in the system PATH.

OPTIONS¶

-1

Run tests in a single thread (same as -j 1)

-C dir

Chdir before running r2r (default follows executable symlink + test/new)

-F dir

Run fuzz tests (open and default analysis) on all files in the given dir

-L

Log mode (better printing for CI, logfiles, etc.)

-V

Verbose

-f file

File to use for json tests (default is bins/elf/crackme0x00b)

-g

Run the tests specified via '// R2R' comments in modified source files

-h

Print help message

-H

Display environment variables

-i

Interactive mode

-j threads

How many threads to use for running tests concurrently (default is 8)

-n

Do nothing (don't run any test, just load/parse them)

-o file

Output test run information in JSON format to file

-q

Quiet (only show errors; suppress non-error output)

-s test

Set R2R_SKIP_(TEST)=1 to skip running that test type

-S percent

Set R2R_SHALLOW=N to skip a random percentage (0-100) of tests

-t seconds

Timeout per test (default is 3600 seconds)

-u

Do not git pull/clone test/bins (See R2R_OFFLINE)

-v

Show version

ENVIRONMENT¶

R2R_SKIP_ARCHOS

Do not run the arch-os-specific tests

R2R_SKIP_JSON

Do not run the JSON tests

R2R_SKIP_FUZZ

Do not run the fuzz tests

R2R_SKIP_UNIT

Do not run the unit tests

R2R_SKIP_CMD

Do not run the cmd tests

R2R_SKIP_ASM

Do not run the rasm2 tests

R2R_JOBS

Maximum parallel jobs (default: 8)

R2R_TIMEOUT

Timeout in seconds (default: 3600 seconds)

R2R_OFFLINE

Same as passing -u flag

R2R_SHALLOW

Skip 0-100% random tests

USAGE¶

Use the -n flag to not run any test. Just load them.

$ r2r -n
[r2r] Loading tests...

Run the tests contained in a directory interactively, if any of those tests fail to run, prompt the user to autofix, edit the commands, etc.

$ r2r -i test/db/cmd/cmd_pdf

Run specific test types using @ notation:

$ r2r @asm # Run assembly tests
$ r2r @json # Run JSON tests
$ r2r @unit # Run unit tests
$ r2r @fuzz # Run fuzz tests
$ r2r @arch # Run architecture-specific tests
$ r2r @cmd # Run command tests

CREATING TESTS¶

r2r loads tests from files under test/db and infers the test type from the path:

test/db/asm/*

Parsed as ASM tests.

test/db/json/*

Parsed as JSON tests.

test/db/leak/*

Parsed as leak tests (command syntax, executed with Valgrind checks).

Other files

Parsed as command tests.

Command-style test files are “KEY=VALUE” records are terminated by “RUN” Every record is validated at load time.

NAME=example
FILE=bins/elf/crackme
ARGS=-a x86 -b 64
CMDS=<<EOF
pd 1
EOF
EXPECT=<<EOF
EOF
RUN

“NORUN” marks a pending record as incomplete, so it is ignored by the parser. Records are loaded only when terminated by “RUN” and otherwise treated as disabled.

TEST RULES¶

Accepted command/leak test keys are handled by R2R_CMD_TEST_FOREACH_RECORD in binr/r2r/r2r.h with the following accepted keys:

NAME

Optional identifier used for reporting.

FILE

Optional file input for the r2 command. You can list multiple files on separate lines. If omitted, stdin “-” is used.

ARGS

Extra arguments passed directly to r2 before “-Qc” and the command block.

REQUIRE

Skip condition string. Supported tokens are “gas, unix, windows, linux, arm, x86, little”. Known host tokens are checked at run time; if unsupported, the test is skipped.

REPEAT

Numeric repeat count. The test command is executed that many times; only the last output is checked.

TIMEOUT

Numeric timeout override for this test in seconds.

SOURCE

Parsed and accepted for compatibility; no additional runtime behavior is wired in.

CMDS

Required command block, passed as “-Qc <CMDS>” Multiline command blocks must use “<<EOF” with the closing token at the beginning of the line. Single-line quoted values are not accepted.

EXPECT

Exact expected stdout match.

EXPECT_ERR

Exact expected stderr match.

REGEXP_OUT

Extended-regex match against stdout.

REGEXP_ERR

Extended-regex match against stderr.

ENV

Semicolon-separated “KEY=VALUE” environment overrides. Tokens missing “=” are ignored.

BROKEN

Boolean (`0`/`1`) marking the test as expected-failing. Failed broken tests are counted as broken instead of failed.

SKIPONASAN

Boolean (`0`/`1`) to skip this test when built with ASAN.

A command/leak test is only accepted when:

1. CMDS is present.
2. Either exact-output or regex-output assertions are present: EXPECT or EXPECT_ERR or REGEXP_OUT or REGEXP_ERR

JSON tests load one command per non-empty, non-comment line from files under test/db/json/*. Empty lines and “#” lines are ignored. If a line contains the word “BROKEN,” the test is marked broken.

ASM tests are parsed line-by-line as

<modes> "<disassembly text>" <hexbytes>[ <offset>]

SEE ALSO¶

radare2(1)

AUTHORS¶

Written by pancake <pancake@nopcode.org>.