testlib for C++ Competitive Programming Tooling

What testlib solves for contest tooling

testlib addresses a specific infrastructure problem in competitive programming: every contest task needs executable components that validate inputs, generate tests, compare answers, or communicate with a submitted solution. Without shared conventions, each component may handle command-line arguments, file input, verdict codes, whitespace, and error reporting differently. That creates avoidable integration work between the contest author and the judging system.

The library targets C++ developers building those components. Its repository includes `checkers/`, `validators/`, `generators/`, and `interactors/`, along with the main `testlib.h` header. The README says the implementation has been used in contests in Russia, including the Russian National Olympiad in Informatics and stages of ICPC, and it has also been used in Codeforces contests. These statements describe reported use by the project documentation, not an independent measure of current adoption.

testlib is therefore not a general testing framework for application unit tests. It is designed around contest-specific artifacts and verdict-oriented execution. Its API exposes operations such as reading constrained values, ending a program with a verdict, registering command-line interfaces, and exchanging data with another process.

The checker and validator execution model

A checker in testlib reads an answer from an input abstraction and a participant result from an output abstraction, then reports success or a failure verdict. The README's sample checker calls `setName`, registers the command line with `registerTestlibCmd`, reads one signed integer from each source, compares them, and calls `quitf` with either `_ok` or `_wa`. The failure message includes both the expected value and the value found.

This design makes the checker executable responsible for judging one candidate output. It does not merely return a Boolean. Instead, the exit path communicates a contest verdict, while the accompanying text explains the result. That distinction matters because competitive programming systems often need to distinguish an accepted answer from a wrong answer and retain diagnostic information for the author or participant.

The validator sample shows stricter input checking. It registers with `registerValidation`, calls `inf.readInt(1, 100, "n")`, then requires `inf.readEoln()` and `inf.readEof()`. Consequently, the validator checks both the permitted integer range and the end-of-line and end-of-file structure. The README explicitly says that it does not ignore whitespace. On Windows it expects `#13#10` as EOLN, while on other platforms it expects `#10`. This makes the validator useful when input formatting is part of the task contract, but it also means that a permissive contest format cannot use this exact example unchanged.

Interactors for solution and process communication

The interactor example covers tasks in which a solution answers queries rather than receiving the entire input once. The executable reads the number of queries from the test input, then reads each pair of integers. It writes each query to standard output using `cout` and `endl`, which flushes the stream according to the example's description. It reads the solution's response through `ouf`, writes that response to `tout`, and later verifies the accumulated output with a checker.

The architecture separates three roles: `inf` represents the test input, the interactor communicates with the solution, and `tout` records responses for later checking. The sample finishes with `quitf(_ok, "%d queries processed", n)`. It also notes that an interactor can terminate with `quitf(_wa, <comment>)`, although the complete rules for deciding when that verdict is appropriate are left to the contest author.

This approach is appropriate for interactive or adaptive tasks. It is not a substitute for a conventional batch checker when the task specification does not define a query and response protocol. The example's reliance on flushed output also makes the interaction contract part of the integration surface: the judging system and submitted solution must agree on when input is ready and when responses are written.

Generators and command-line configuration

Generators use `registerGen(argc, argv, 1)` to establish the generator command-line interface. The first sample prints a random integer in `[1,10]` and then a random token matching `[a-zA-Z0-9]{1,1000}`. The README explains that the generator uses a uniformly distributed random generator and that different command-line parameters produce different values. It describes setting `randseed` through the command line as typical testlib generator behavior.

The second example reads the first command-line argument as an integer, prints it, and prints a random permutation of size `n`. This shows that generators can produce both scalar test parameters and structured data. The generator's output goes to standard output, so a contest data pipeline can capture that output as a test file or feed it into another validation step.

The examples do not provide a complete list of supported command-line options, random-number guarantees beyond the stated distribution, or a formal file format for generated test cases. They also do not document a standalone installation command. The visible integration model is source inclusion: examples include `"testlib.h"`, and the repository exposes that header at its top level.

Installation limits and a first C++ use

The README does not give package-manager installation steps or a build command. It provides C++ examples that include `testlib.h`, and the repository layout includes that header plus example directories. A first use therefore begins by placing the repository's `testlib.h` where the compiler can include it, then compiling a checker, validator, generator, or interactor as a normal C++ executable. The documentation states compatibility with standard C++11 and later versions of `g++`, `clang++`, and Microsoft Visual C++, but it does not specify exact compiler invocations.

The simplest first component is the validator example because it has no comparison logic beyond the documented input contract. Its source is:

#include "testlib.h"

int main(int argc, char * argv[]) {
    registerValidation(argc, argv);
    inf.readInt(1, 100, "n");
    inf.readEoln();
    inf.readEof();
}

This code accepts only one integer from 1 through 100 and then checks the expected line ending and file termination. The README says invalid input produces a non-zero code and a message on standard output. It does not document installation through a package manager, and it does not claim that this header is self-contained for every build system. The first verification should therefore focus on include resolution, compiler compatibility, and the command-line contract used by the surrounding contest runner.

Compatibility, maintenance, and license cost

The repository is not archived, and its last push was on 2026-08-27. That is the maintenance fact available here. The latest listed release is version 0.9.41, dated 2023-10-06, while older listed releases include 0.9.12 from 2017-04-12 and 0.9.11 from 2016-12-29. The repository's release history therefore does not by itself establish a regular release cadence.

The README states compatibility with C++11 and higher across several `g++`, `clang++`, and Microsoft Visual C++ versions. That is a portability statement from the project documentation, not a claim that every current compiler version is supported. Because testlib is distributed as a C++ header-oriented repository in this layout, an upgrade may involve replacing the header and checking the examples used by a contest system. The README does not document a migration process, compatibility policy between releases, or rollback procedure.

The repository lists the MIT license. That gives the project an open source license grant, but license interpretation depends on the complete `LICENSE` file and the user's circumstances. The license does not by itself answer whether a particular judging service permits a derived checker or how organizers should package internal contest infrastructure. The practical upgrade cost is therefore tied mainly to compiler compatibility, changes to local helpers, and verification against the contest runner.

Editorial conclusion

testlib is a practical choice for contest authors who need a shared C++ convention for checkers, validators, generators, and interactors, especially across Codeforces, ICPC, or similar event tooling. It is less suitable when a team requires a documented installation process, a modern package workflow, or support outside the C++ ecosystem. Review the included examples and confirm that your contest runner uses the command-line interfaces and exit behavior expected by the library before adopting it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MikeMirzayanov/testlib on GitHub
4. README
5. Releases