Progmasoft Git

catch3

Progmasoft Catch3: an independently maintained C++17 test framework with a parallel runner, property checks, snapshots and structured results.

Clonegit clone https://git.progmasoft.com/catch3

develroot / src / Progmasoft / Catch3 / Stateful.hpp

5.9 KiB · Raw · Log

// Copyright (c) 2026 Progmasoft.
// SPDX-License-Identifier: LGPL-3.0-or-later
#pragma once

#include <Progmasoft/Catch3/ForAll.hpp>
#include <Progmasoft/Catch3/Strategy/Containers.hpp>
#include <functional>
#include <optional>
#include <string>
#include <utility>
#include <vector>

namespace Progmasoft::Catch3
{

    /// One step of a stateful test: a description for the report and the
    /// code that applies the step to the model and to the system under
    /// test. It checks the system against the model with
    /// CATCH3_PROPERTY_ASSERT.
    template<typename Model, typename System>
    struct Action final
    {
        std::string Description;
        std::function<void(Model &, System &)> Apply;
    };

    /// A kind of step. Make builds the step from the current model, so its
    /// arguments can depend on the state, for example by choosing a key
    /// that the model holds. Precondition says whether the step may run in
    /// a state; an unset precondition always holds.
    template<typename Model, typename System>
    struct Command final
    {
        std::string Name;
        std::function<Strategy<Action<Model, System>>(const Model &)> Make;
        std::function<bool(const Model &)> Precondition = {};
    };

    /// A command without arguments.
    template<typename Model, typename System, typename Apply>
    [[nodiscard]] Command<Model, System>
    MakeCommand(std::string name, Apply apply)
    {
        return Command<Model, System>{
            name,
            [name, apply](const Model &) {
                return Gen::Just(Action<Model, System>{ name, apply });
            },
        };
    }

    namespace Detail
    {

        template<typename Model, typename System>
        [[nodiscard]] TrialOutcome
        RunCommands(ChoiceSource &source,
                    bool describe,
                    const std::function<Model()> &initialModel,
                    const std::function<System(const Model &)> &makeSystem,
                    const std::vector<Command<Model, System>> &commands,
                    const SizeRange &steps)
        {
            TrialOutcome outcome;
            Model model = initialModel();
            std::optional<System> system;
            std::vector<std::string> log;
            {
                TrialRecordScope scope(outcome.Record);
                system.emplace(makeSystem(model));
            }
            const auto addStep = [&]() -> bool {
                // The choice names a command; when its precondition does not
                // hold, the next commands are tried in order, so that the
                // same choice always leads to the same command.
                const std::size_t first = static_cast<std::size_t>(
                    source.Draw(commands.size() - 1U));
                const Command<Model, System> *chosen = nullptr;
                for (std::size_t offset = 0; offset < commands.size(); ++offset)
                {
                    const auto &candidate
                        = commands[(first + offset) % commands.size()];
                    if (!candidate.Precondition || candidate.Precondition(model))
                    {
                        chosen = &candidate;
                        break;
                    }
                }
                if (chosen == nullptr)
                {
                    return false;
                }
                auto action = DrawGuarded(chosen->Make(model), source, outcome);
                if (!action.has_value())
                {
                    return false;
                }
                log.push_back(action->Description);
                RunBody(
                    [&]() { action->Apply(model, *system); },
                    std::tuple<>(),
                    outcome);
                return outcome.Verdict == TrialVerdict::kPassed;
            };
            (void)Detail::DrawElements(source, steps, addStep);
            if (outcome.Verdict == TrialVerdict::kInvalid && !log.empty())
            {
                // A step that could not be built ends the sequence; the
                // steps before it still ran and passed.
                outcome.Verdict = TrialVerdict::kPassed;
            }
            if (describe)
            {
                std::string text = "{";
                for (std::size_t index = 0; index < log.size(); ++index)
                {
                    text += index == 0 ? " " : ", ";
                    text += log[index];
                }
                outcome.Description = text + (log.empty() ? "}" : " }");
            }
            return outcome;
        }

    } // namespace Detail

    /// Model-based testing: runs random sequences of commands against a
    /// model and the system under test, side by side. A failing sequence
    /// shrinks to a short one with simple arguments, since dropping a step
    /// is deleting its choices.
    template<typename Model, typename System>
    [[nodiscard]] PropertyResult
    CheckStateful(const PropertyOptions &options,
                  std::function<Model()> initialModel,
                  std::function<System(const Model &)> makeSystem,
                  std::vector<Command<Model, System>> commands,
                  SizeRange steps = {})
    {
        if (commands.empty())
        {
            Detail::RejectInvalidArgument(
                "CheckStateful requires at least one command");
        }
        Detail::CheckRange(steps);
        const Detail::TrialRunner runner
            = [&](ChoiceSource &source, bool describe) {
                  return Detail::RunCommands(source,
                                             describe,
                                             initialModel,
                                             makeSystem,
                                             commands,
                                             steps);
              };
        return Detail::RunPropertyEngine(options, runner);
    }

} // namespace Progmasoft::Catch3