tiny.tripwire.failpoint

1const std = @import("std");2const builtin = @import("builtin");3const assert = std.debug.assert;4const testing = std.testing;56fn TripwireType(comptime Error: type) type {7    return struct {8        err: Error,9        reached: usize = 0,10        min: usize = 0,11        tripped: bool = false,12    };13}1415/// Creates a failpoint module at compile time for the failpoint enum `P` and16/// the error specification `E`: the namespace that holds one group of named17/// check sites.18///19/// - `P` is an enum whose fields name the check sites.20/// - `E` is one of four things: an error set type such as `anyerror` or21///   `error{...}`, an error union type such as `E!T`, a function type whose22///   return is an error union such as `fn (...) E!T`, or a function value that23///   declares such a return. An error value such as `error.OutOfMemory` does24///   not work as `E`, because the error set case hands `E` straight back and25///   the result has to be a type.26///27/// Every caller naming the same `P` and `E` shares one state map, which belongs28/// to the returned type, so no instance of the returned type carries the state.29/// Nothing synchronizes the state across threads.30pub fn module(31    comptime P: type,32    comptime E: anytype,33) type {34    return struct {35        /// The enum type whose tags name the check sites of this failpoint36        /// module, named here so a caller can write out the type that other37        /// functions take.38        pub const FailPoint: type = P;3940        /// The error set read out of the error specification at compile time,41        /// which `check` returns so a caller can match an enclosing function's42        /// error set against it.43        pub const Error: type = err: {44            const T = if (@TypeOf(E) == type) E else @TypeOf(E);45            break :err switch (@typeInfo(T)) {46                .error_set => E,47                .error_union => |info| info.error_set,48                .@"fn" => |info| @typeInfo(info.return_type.?).error_union.error_set,49                else => @compileError("E must be an error set or function type"),50            };51        };5253        /// The compile-time flag that turns the checks on, true in a test build54        /// and false everywhere else.55        pub const enabled = builtin.is_test;5657        comptime {58            assert(@typeInfo(FailPoint) == .@"enum");59            assert(@typeInfo(Error) == .error_set);60        }6162        var tripwires: TripwireMap = .{};6364        const TripwireMap: type = std.EnumMap(FailPoint, Tripwire);65        const Tripwire: type = TripwireType(Error);6667        /// Evaluates the check site named by `point` inside an operation where68        /// a simulated error should arrive, so a test can drive the error path69        /// that a successful run leaves alone.70        ///71        /// - Where `enabled` is false, meaning `builtin.is_test == false`, the72        ///   call is an inlined no-op that returns `void`.73        /// - In a test build, the call returns `void` when `point` has no74        ///   configuration or while the visit count stands at or below the75        ///   threshold. Once the visit count passes the threshold, the site is76        ///   marked tripped and the configured error is returned. The error77        ///   comes back on every later visit as well, as long as the visit78        ///   count stays inside `usize` range.79        pub fn check(point: FailPoint) callconv(callingConvention()) Error!void {80            if (comptime !enabled) return;81            return checkConstrained(point, Error);82        }8384        /// Evaluates the check site named by `point` and returns an error typed85        /// as `ConstrainedError`, letting the check sit inside a function whose86        /// declared error set is wider than the module's own.87        ///88        /// - Where `enabled` is false, the call is an inlined no-op that89        ///   returns `void`.90        /// - In a test build, it follows the same visit count and threshold91        ///   rules as `check`.92        /// - The typing requirement in a test build comes from the body: it93        ///   runs `return tripwire.err;`, and that value has type `Error`. Zig94        ///   coerces an error set only into a set that holds it, so95        ///   `ConstrainedError` has to be `Error` or a superset of `Error`.96        pub fn checkConstrained(97            point: FailPoint,98            comptime ConstrainedError: type,99        ) callconv(callingConvention()) ConstrainedError!void {100            if (comptime !enabled) return;101            const tripwire = tripwires.getPtr(point) orelse return;102            tripwire.reached += 1;103            if (tripwire.reached <= tripwire.min) return;104            tripwire.tripped = true;105            return tripwire.err;106        }107108        /// Provides the one-line setup for a test that wants the site to fail109        /// the first time an operation reaches it, configuring `point` to110        /// deliver `err` on its first visit, which is a threshold of 0. The111        /// call replaces whatever configuration `point` already had, putting112        /// the visit count back to 0 and the trip flag back to false. In a test113        /// build, later calls to `check(point)` follow the visit count rules114        /// written on `check`.115        pub fn errorAlways(point: FailPoint, err: Error) void {116            errorAfter(point, err, 0);117        }118119        /// Lets earlier visits through when an operation reaches the same site120        /// more than once before reaching the state the test targets, for121        /// example while parsing earlier records or running earlier loop122        /// iterations. The function configures `point` to pass its first `min`123        /// visits and to deliver `err` on visit `min + 1` and on every visit124        /// after that. This registration replaces whatever configuration125        /// `point` already had, putting the visit count back to 0 and the trip126        /// flag back to false. In a test build, later calls to `check(point)`127        /// follow the visit count rules written on `check`.128        pub fn errorAfter(point: FailPoint, err: Error, min: usize) void {129            tripwires.put(point, .{ .err = err, .min = min });130        }131132        /// Settles whether a test reached its configured sites, because a133        /// passing test proves its error path only once the site is known to134        /// have been reached. The function verifies that every configured site135        /// in the failpoint module was visited past its threshold and tripped.136        ///137        /// - With no site configured, it succeeds at once.138        /// - With any configured site still untripped, it returns139        ///   `error.UntrippedError`.140        /// - Under `.reset`, it clears every configured site, including on the141        ///   run that returns the error.142        /// - Under `.retain`, it keeps the registrations and the counters, so143        ///   the trip flags stay set and a later call passes with no further144        ///   visits in between.145        ///146        /// The call proves that the configured error was delivered at the check147        /// site. Whether the caller caught the error, ran its cleanup, or held148        /// its domain invariants is left to the test's own assertions.149        pub fn end(reset_mode: enum { reset, retain }) error{UntrippedError}!void {150            var untripped = false;151            var iter = tripwires.iterator();152            while (iter.next()) |entry| {153                if (!entry.value.tripped) {154                    untripped = true;155                }156            }157158            switch (reset_mode) {159                .reset => reset(),160                .retain => {},161            }162163            if (untripped) return error.UntrippedError;164        }165166        /// Clears every failpoint registration and the counters behind them. A167        /// test calls it before it starts and again on the way out, because168        /// that state belongs to the type and outlives any one test.169        pub fn reset() void {170            tripwires = .{};171        }172173        fn callingConvention() std.builtin.CallingConvention {174            return if (!enabled) .@"inline" else .auto;175        }176    };177}178179const TestFailPoint = enum {180    anonymous_read,181    anonymous_write,182};183184fn test_error_function() error{ Foo, Bar }!void {185    return error.Foo;186}187188test {189    const io = module(TestFailPoint, anyerror);190    io.reset();191    defer io.reset();192193    try io.end(.reset);194    try io.check(.anonymous_read);195196    io.errorAlways(.anonymous_read, error.OutOfMemory);197    try testing.expectError(error.OutOfMemory, io.check(.anonymous_read));198    try testing.expectError(error.OutOfMemory, io.check(.anonymous_read));199    try io.end(.reset);200}201202test "module as error set" {203    const io = module(enum { error_set_read, error_set_write }, @TypeOf(test_error_function));204    io.reset();205    defer io.reset();206    try io.end(.reset);207}208209test "errorAfter" {210    const io = module(enum { after_read, after_write }, anyerror);211    io.reset();212    defer io.reset();213    io.errorAfter(.after_read, error.OutOfMemory, 2);214215    try io.check(.after_read);216    try io.check(.after_read);217218    try testing.expectError(error.OutOfMemory, io.check(.after_read));219    try testing.expectError(error.OutOfMemory, io.check(.after_read));220221    try io.end(.reset);222}223224test "errorAfter reports untripped expectations" {225    const io = module(enum { untripped_read }, anyerror);226    io.reset();227    defer io.reset();228    io.errorAfter(.untripped_read, error.OutOfMemory, 2);229    try io.check(.untripped_read);230    try testing.expectError(error.UntrippedError, io.end(.reset));231}

1/// The implementation of the package, holding the generic constructor and the2/// runtime logic behind every check site.3pub const failpoint = @import("failpoint.zig");