test_utils.hpp

/*
 * This file is part of libtcspc
 * Copyright 2019-2026 Board of Regents of the University of Wisconsin System
 * SPDX-License-Identifier: MIT
 */
 
#pragma once
 
#include "bucket.hpp"
#include "common.hpp"
#include "context.hpp"
#include "errors.hpp"
#include "event.hpp"
#include "introspect.hpp"
#include "numeric_traits.hpp"
#include "processor.hpp"
#include "type_list.hpp"
#include "variant_event.hpp"
#include "vector_queue.hpp"
 
#include <algorithm>
#include <any>
#include <array>
#include <cassert>
#include <concepts>
#include <cstdint>
#include <cstdio>
#include <initializer_list>
#include <limits>
#include <memory>
#include <ostream>
#include <span>
#include <sstream>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <typeinfo>
#include <utility>
#include <variant>
#include <vector>
 
namespace tcspc {
 
namespace internal {
 
template <typename EventList> class sink_only {
  public:
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "sink_only");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return processor_graph().push_entry_point(this);
    }
 
    template <typename E>
        requires convertible_to_type_list_member<std::remove_cvref_t<E>,
                                                 EventList>
    void handle(E &&event) {
        [[maybe_unused]] std::remove_reference_t<E> const e =
            std::forward<E>(event);
    }
 
    void flush() {}
};
 
} // namespace internal

template <typename... Event> auto sink_only() {
    return internal::sink_only<type_list<Event...>>();
}

template <typename EventList> auto sink_only_list() {
    return internal::sink_only<EventList>();
}

enum class feed_as {
    const_lvalue,
    rvalue,
};

inline auto operator<<(std::ostream &stream, feed_as cat) -> std::ostream & {
    switch (cat) {
    case feed_as::const_lvalue:
        return stream << "feed_as::const_lvalue";
    case feed_as::rvalue:
        return stream << "feed_as::rvalue";
    }
    internal::unreachable();
}

enum class emitted_as {
    any_allowed,
    same_as_fed,
    always_lvalue,
    always_rvalue,
};

inline auto operator<<(std::ostream &stream, emitted_as cat)
    -> std::ostream & {
    switch (cat) {
    case emitted_as::any_allowed:
        return stream << "emitted_as::any_allowed";
    case emitted_as::same_as_fed:
        return stream << "emitted_as::same_as_fed";
    case emitted_as::always_lvalue:
        return stream << "emitted_as::always_lvalue";
    case emitted_as::always_rvalue:
        return stream << "emitted_as::always_rvalue";
    }
    internal::unreachable();
}
 
namespace internal {
 
// Value category observed by capture_output.
enum class emitted_value_category {
    const_lvalue,
    nonconst_lvalue,
    const_rvalue,
    nonconst_rvalue,
};
 
inline void check_value_category(feed_as feed_cat, emitted_as expected,
                                 emitted_value_category actual) {
    if (actual == emitted_value_category::nonconst_lvalue)
        throw std::logic_error("non-const lvalue event not allowed");
 
    if (expected == emitted_as::same_as_fed) {
        switch (feed_cat) {
        case feed_as::const_lvalue:
            expected = emitted_as::always_lvalue;
            break;
        case feed_as::rvalue:
            expected = emitted_as::always_rvalue;
            break;
        }
    }
 
    switch (expected) {
    case emitted_as::any_allowed:
        break;
    case emitted_as::same_as_fed:
        unreachable();
    case emitted_as::always_lvalue:
        if (actual == emitted_value_category::nonconst_rvalue)
            throw std::logic_error("expected lvalue event, found rvalue");
        break;
    case emitted_as::always_rvalue:
        if (actual != emitted_value_category::nonconst_rvalue)
            throw std::logic_error("expected rvalue event, found lvalue");
        break;
    }
}
 
inline auto operator<<(std::ostream &stream, emitted_value_category cat)
    -> std::ostream & {
    switch (cat) {
        using e = emitted_value_category;
    case e::const_lvalue:
        return stream << "const &";
    case e::nonconst_lvalue:
        return stream << "&";
    case e::const_rvalue:
        return stream << "const &&";
    case e::nonconst_rvalue:
        return stream << "&&";
    }
    unreachable();
}
 
template <typename EventList>
using recorded_event =
    std::pair<emitted_value_category, variant_event<EventList>>;
 
template <typename EventList>
auto operator<<(std::ostream &stream, recorded_event<EventList> const &pair)
    -> std::ostream & {
    return stream << pair.second << ' ' << pair.first;
}
 
// Polymorphic function set for type-erasing capture_output_accessor.
class capture_output_accessor_impl_base {
  public:
    virtual ~capture_output_accessor_impl_base() = default;
    // Returned std::any contains std::vector<recorded_event<EventList>>.
    [[nodiscard]] virtual auto peek_events() const -> std::any = 0;
    virtual void pop_event() = 0;
    [[nodiscard]] virtual auto is_empty() const -> bool = 0;
    [[nodiscard]] virtual auto is_flushed() const -> bool = 0;
    virtual void set_up_to_throw(std::size_t count, bool use_error) = 0;
    [[nodiscard]] virtual auto events_as_string() const -> std::string = 0;
};
 
} // namespace internal

class capture_output_accessor {
    std::unique_ptr<internal::capture_output_accessor_impl_base> impl;
 
    template <typename EventList>
    auto peek_events() const
        -> std::vector<internal::recorded_event<EventList>> {
        return std::any_cast<std::vector<internal::recorded_event<EventList>>>(
            impl->peek_events());
    }
 
  public:
    explicit capture_output_accessor(
        std::unique_ptr<internal::capture_output_accessor_impl_base>
            implementation)
        : impl(std::move(implementation)) {}

    void check_ready_for_input(std::string const &input) const {
        if (not impl->is_empty()) {
            throw std::logic_error(
                "cannot accept input (" + input +
                "): recorded output events remain unchecked:" +
                impl->events_as_string());
        }
        if (impl->is_flushed()) {
            throw std::logic_error("cannot accept input (" + input +
                                   "): output has been flushed");
        }
    }

    template <typename Event, typename EventList>
    auto pop(feed_as feeder_value_category, emitted_as value_category)
        -> Event {
        static_assert(type_list_member<Event, EventList>);
        auto const events = peek_events<EventList>();
        try {
            if (events.empty())
                throw std::logic_error("missing event");
            check_value_category(feeder_value_category, value_category,
                                 events.front().first);
            auto const *event = std::get_if<Event>(&events.front().second);
            if (event == nullptr)
                throw std::logic_error("type mismatch");
            impl->pop_event();
            return *event;
        } catch (std::logic_error const &exc) {
            std::ostringstream stream;
            stream << "event pop failed: " << exc.what() << '\n';
            stream << "expected recorded output event of type "
                   << std::string(typeid(Event).name()) << " ("
                   << feeder_value_category << ", " << value_category
                   << ") but found";
            if (events.empty()) {
                stream << " no events";
            } else {
                stream << ':';
                for (auto const &e : events)
                    stream << '\n' << e;
            }
            throw std::logic_error(stream.str());
        }
    }

    template <typename Event, typename EventList>
    auto check(feed_as feeder_value_category, emitted_as value_category,
               Event const &expected_event) -> bool {
        static_assert(type_list_member<Event, EventList>);
        auto events = peek_events<EventList>();
        try {
            if (events.empty())
                throw std::logic_error("missing event");
            check_value_category(feeder_value_category, value_category,
                                 events.front().first);
            auto const *event = std::get_if<Event>(&events.front().second);
            if (event == nullptr)
                throw std::logic_error("type mismatch");
            if (*event != expected_event)
                throw std::logic_error("value mismatch");
            impl->pop_event();
            return true;
        } catch (std::logic_error const &exc) {
            std::ostringstream stream;
            stream << "event check failed: " << exc.what() << '\n';
            stream << "expected recorded output event " << expected_event
                   << " (" << feeder_value_category << ", " << value_category
                   << ") but found";
            if (events.empty()) {
                stream << " no events";
            } else {
                stream << ':';
                for (auto const &e : events)
                    stream << '\n' << e;
            }
            throw std::logic_error(stream.str());
        }
    }

    auto check_not_flushed() -> bool {
        if (not impl->is_empty()) {
            throw std::logic_error(
                "expected no recorded output events but found:" +
                impl->events_as_string());
        }
        if (impl->is_flushed()) {
            throw std::logic_error(
                "expected output unflushed but found flushed");
        }
        return true;
    }

    auto check_flushed() -> bool {
        if (not impl->is_empty()) {
            throw std::logic_error(
                "expected no recorded output events but found:" +
                impl->events_as_string());
        }
        if (not impl->is_flushed()) {
            throw std::logic_error(
                "expected output flushed but found unflushed");
        }
        return true;
    }

    void throw_error_on_next(std::size_t count = 0) {
        impl->set_up_to_throw(count, true);
    }

    void throw_end_processing_on_next(std::size_t count = 0) {
        impl->set_up_to_throw(count, false);
    }

    void throw_error_on_flush() {
        impl->set_up_to_throw(std::numeric_limits<std::size_t>::max(), true);
    }

    void throw_end_processing_on_flush() {
        impl->set_up_to_throw(std::numeric_limits<std::size_t>::max(), false);
    }
};

template <typename EventList> class capture_output_checker {
    capture_output_accessor acc;
 
    feed_as feeder_valcat;
 
  public:
    explicit capture_output_checker(feed_as feeder_value_category,
                                    capture_output_accessor accessor)
        : acc(std::move(accessor)), feeder_valcat(feeder_value_category) {}

    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init)
    explicit capture_output_checker(feed_as feeder_value_category,
                                    std::shared_ptr<context> context,
                                    std::string const &name)
        : capture_output_checker(
              feeder_value_category,
              context->access<capture_output_accessor>(name)) {}

    template <typename Event> auto pop() -> Event {
        return pop<Event>(emitted_as::any_allowed);
    }

    template <typename Event> auto pop(emitted_as value_category) -> Event {
        static_assert(type_list_member<Event, EventList>);
        return acc.pop<Event, EventList>(feeder_valcat, value_category);
    }

    template <typename Event> auto check(Event const &expected_event) -> bool {
        return check(emitted_as::any_allowed, expected_event);
    }

    template <typename Event>
    auto check(emitted_as value_category, Event const &expected_event)
        -> bool {
        static_assert(type_list_member<Event, EventList>);
        return acc.check<Event, EventList>(feeder_valcat, value_category,
                                           expected_event);
    }

    auto check_not_flushed() -> bool { return acc.check_not_flushed(); }

    auto check_flushed() -> bool { return acc.check_flushed(); }

    void throw_error_on_next(std::size_t count = 0) {
        acc.throw_error_on_next(count);
    }

    void throw_end_processing_on_next(std::size_t count = 0) {
        acc.throw_end_processing_on_next(count);
    }

    void throw_error_on_flush() { acc.throw_error_on_flush(); }

    void throw_end_processing_on_flush() {
        acc.throw_end_processing_on_flush();
    }
};
 
namespace internal {
 
template <typename EventList> class capture_output {
    static_assert(type_list_like<EventList>);
    static_assert(
        is_copy_constructible_list_v<EventList>,
        "capture_output requires every event in EventList to be "
        "copy-constructible (recorded events are copied for inspection)");
    static_assert(is_equality_comparable_list_v<EventList>,
                  "capture_output requires every event in EventList to be "
                  "std::equality_comparable (used by check())");
    static_assert(
        is_ostreamable_list_v<EventList>,
        "capture_output requires every event in EventList to provide "
        "operator<< to std::ostream (used by events_as_string() and "
        "Catch2 stringification)");
 
    vector_queue<recorded_event<EventList>> output;
    bool flushed = false;
    std::size_t error_in = std::numeric_limits<std::size_t>::max();
    std::size_t end_in = std::numeric_limits<std::size_t>::max();
    bool error_on_flush = false;
    bool end_on_flush = false;
 
    access_tracker<capture_output_accessor> trk;
 
    struct accessor_impl : capture_output_accessor_impl_base {
        capture_output *self;
 
        explicit accessor_impl(capture_output *self) : self(self) {}
 
        [[nodiscard]] auto peek_events() const -> std::any final {
            return self->peek();
        }
        void pop_event() final { self->output.pop(); }
        [[nodiscard]] auto is_empty() const -> bool final {
            return self->output.empty();
        }
        [[nodiscard]] auto is_flushed() const -> bool final {
            return self->flushed;
        }
        void set_up_to_throw(std::size_t count, bool use_error) final {
            self->set_up_to_throw(count, use_error);
        }
        [[nodiscard]] auto events_as_string() const -> std::string final {
            return self->events_as_string();
        }
    };
 
    auto peek() const {
        std::vector<recorded_event<EventList>> ret;
        ret.reserve(output.size());
        // Cannot use std::copy because vector_queue lacks iterators.
        output.for_each([&ret](auto const &pair) { ret.push_back(pair); });
        return ret;
    }
 
    [[nodiscard]] auto events_as_string() const -> std::string {
        std::ostringstream stream;
        output.for_each([&](auto const &event) { stream << '\n' << event; });
        return stream.str();
    }
 
    void set_up_to_throw(std::size_t count, bool use_error) {
        if (count == std::numeric_limits<std::size_t>::max()) {
            if (use_error)
                error_on_flush = true;
            else
                end_on_flush = true;
        } else {
            if (use_error)
                error_in = count;
            else
                end_in = count;
        }
    }
 
  public:
    explicit capture_output(access_tracker<capture_output_accessor> &&tracker)
        : trk(std::move(tracker)) {
        trk.register_accessor_factory([](auto &tracker) {
            auto *self =
                LIBTCSPC_OBJECT_FROM_TRACKER(capture_output, trk, tracker);
            return capture_output_accessor(
                std::make_unique<accessor_impl>(self));
        });
    }
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "capture_output");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return processor_graph().push_entry_point(this);
    }
 
    template <typename Event>
        requires type_list_member<std::remove_cvref_t<Event>, EventList>
    void handle(Event &&event) {
        static constexpr auto valcat = [] {
            if constexpr (std::is_lvalue_reference_v<Event>) {
                if constexpr (std::is_const_v<std::remove_reference_t<Event>>)
                    return emitted_value_category::const_lvalue;
                else
                    return emitted_value_category::nonconst_lvalue;
            } else {
                if constexpr (std::is_const_v<Event>)
                    return emitted_value_category::const_rvalue;
                else
                    return emitted_value_category::nonconst_rvalue;
            }
        }();
        assert(not flushed);
        if (error_in == 0)
            throw test_error("test error upon event");
        output.push(std::pair{valcat, std::forward<Event>(event)});
        if (end_in == 0)
            throw end_of_processing("test end-of-stream upon event");
        --error_in;
        --end_in;
    }
 
    void flush() {
        assert(not flushed);
        if (error_on_flush) {
            throw test_error("test error upon flush");
        }
        flushed = true;
        if (end_on_flush)
            throw end_of_processing("test end-of-stream upon flush");
    }
};
 
// Specialization for empty event list.
template <> class capture_output<type_list<>> {
    bool flushed = false;
    bool error_on_flush = false;
    bool end_on_flush = false;
    access_tracker<capture_output_accessor> trk;
 
    struct accessor_impl : capture_output_accessor_impl_base {
        capture_output *self;
 
        explicit accessor_impl(capture_output *self) : self(self) {}
 
        [[noreturn]] static void not_allowed() {
            throw std::logic_error(
                "operation not allowed on capture_output with empty event list");
        }
 
        [[nodiscard]] auto peek_events() const -> std::any final {
            not_allowed();
        }
        void pop_event() final { not_allowed(); }
        [[nodiscard]] auto is_empty() const -> bool final { return true; }
        [[nodiscard]] auto is_flushed() const -> bool final {
            return self->flushed;
        }
        void set_up_to_throw(std::size_t /* count */,
                             bool /* use_error */) final {
            not_allowed();
        }
        [[nodiscard]] auto events_as_string() const -> std::string final {
            not_allowed();
        }
    };
 
    void set_up_to_throw(std::size_t count, bool use_error) {
        if (count == std::numeric_limits<std::size_t>::max()) {
            if (use_error)
                error_on_flush = true;
            else
                end_on_flush = true;
        }
    }
 
  public:
    explicit capture_output(access_tracker<capture_output_accessor> &&tracker)
        : trk(std::move(tracker)) {
        trk.register_accessor_factory([](auto &tracker) {
            auto *self =
                LIBTCSPC_OBJECT_FROM_TRACKER(capture_output, trk, tracker);
            return capture_output_accessor(
                std::make_unique<accessor_impl>(self));
        });
    }
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "capture_output");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return processor_graph().push_entry_point(this);
    }
 
    void flush() {
        assert(not flushed);
        if (error_on_flush) {
            throw test_error("test error upon flush");
        }
        flushed = true;
        if (end_on_flush)
            throw end_of_processing("test end-of-stream upon flush");
    }
};
 
template <typename Downstream>
    requires processor<Downstream>
class feed_input {
    std::vector<std::pair<std::shared_ptr<context>, std::string>>
        outputs_to_check; // (context, name)
    feed_as refmode = feed_as::const_lvalue;
    Downstream downstream;
 
    void check_outputs_ready(std::string const &input) {
        if (outputs_to_check.empty())
            throw std::logic_error(
                "feed_input has no registered capture_output to check");
        for (auto &[context, name] : outputs_to_check)
            context->template access<capture_output_accessor>(name)
                .check_ready_for_input(input);
    }
 
  public:
    explicit feed_input(Downstream downstream)
        : downstream(std::move(downstream)) {}
 
    explicit feed_input(feed_as mode, Downstream downstream)
        : refmode(mode), downstream(std::move(downstream)) {}
 
    [[nodiscard]] auto introspect_node() const -> processor_info {
        return processor_info(this, "feed_input");
    }
 
    [[nodiscard]] auto introspect_graph() const -> processor_graph {
        return downstream.introspect_graph().push_entry_point(this);
    }
 
    void require_output_checked(std::shared_ptr<context> context,
                                std::string name) {
        context->access<capture_output_accessor>(name); // Fail early.
        outputs_to_check.emplace_back(std::move(context), std::move(name));
    }
 
    template <typename Event>
        requires handler_for<Downstream, std::remove_cvref_t<Event>>
    void handle(Event &&event) {
        check_outputs_ready("event of type " +
                            std::string(typeid(event).name()));
 
        if (refmode == feed_as::const_lvalue) {
            downstream.handle(static_cast<Event const &>(event));
        } else if constexpr (std::is_lvalue_reference_v<Event>) {
            std::remove_cvref_t<Event> copy(event);
            downstream.handle(std::move(copy));
        } else {
            downstream.handle(std::forward<Event>(event));
        }
    }
 
    void flush() {
        check_outputs_ready("flush");
        downstream.flush();
    }
};
 
} // namespace internal

template <typename EventList>
auto capture_output(access_tracker<capture_output_accessor> &&tracker) {
    return internal::capture_output<EventList>(std::move(tracker));
}

template <typename Downstream>
auto feed_input(feed_as value_category, Downstream downstream) {
    return internal::feed_input<Downstream>(value_category,
                                            std::move(downstream));
}

template <int N> struct empty_test_event {
    friend auto operator==(empty_test_event<N> const &lhs,
                           empty_test_event<N> const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &strm,
                           empty_test_event<N> const & /* e */)
        -> std::ostream & {
        return strm << "empty_test_event<" << N << ">";
    }
};

template <int N, typename NumericTraits = default_numeric_traits>
struct time_tagged_test_event {
    NumericTraits::abstime_type abstime;

    friend auto operator==(time_tagged_test_event const &lhs,
                           time_tagged_test_event const &rhs) noexcept
        -> bool = default;

    friend auto operator<<(std::ostream &strm, time_tagged_test_event const &e)
        -> std::ostream & {
        return strm << "time_tagged_test_event<" << N << ">{" << e.abstime
                    << "}";
    }
};

template <typename T>
auto test_bucket(std::initializer_list<T> il) -> bucket<T> {
    using U = std::remove_cv_t<T>;
    struct test_storage {
        std::vector<U> v;
    };
    auto storage = test_storage{std::vector<U>(il.begin(), il.end())};
    return bucket<T>(std::span(storage.v), std::move(storage));
}

template <typename T> auto test_bucket(std::span<T> s) -> bucket<T> {
    using U = std::remove_cv_t<T>;
    struct test_storage {
        std::vector<U> v;
    };
    auto storage = test_storage{std::vector<U>(s.begin(), s.end())};
    return bucket<T>(std::span(storage.v), std::move(storage));
}

template <typename T> class test_bucket_source : public bucket_source<T> {
    std::shared_ptr<bucket_source<T>> src;
    T value;
    std::size_t count = 0;
 
    explicit test_bucket_source(
        std::shared_ptr<bucket_source<T>> backing_source, T fill_value)
        : src(std::move(backing_source)), value(std::move(fill_value)) {}
 
  public:
    static auto create(std::shared_ptr<bucket_source<T>> backing_source,
                       T fill_value)
        -> std::shared_ptr<test_bucket_source<T>> {
        return std::shared_ptr<test_bucket_source<T>>(new test_bucket_source(
            std::move(backing_source), std::move(fill_value)));
    }

    auto bucket_of_size(std::size_t size) -> bucket<T> override {
        auto b = src->bucket_of_size(size);
        std::fill(b.begin(), b.end(), value);
        ++count;
        return b;
    }

    [[nodiscard]] auto bucket_count() const noexcept -> std::size_t {
        return count;
    }

    [[nodiscard]] auto supports_shared_views() const noexcept
        -> bool override {
        return src->supports_shared_views();
    }

    [[nodiscard]] auto shared_view_of(bucket<T> const &bkt)
        -> bucket<T const> override {
        return src->shared_view_of(bkt);
    }
};

template <typename Event>
inline auto
from_reversed_bytes(std::array<std::uint8_t, sizeof(Event)> bytes) noexcept {
    static_assert(std::is_trivial_v<Event>);
    auto const srcspan = std::as_bytes(std::span(&bytes, 1));
    Event ret{};
    auto const retspan = std::as_writable_bytes(std::span(&ret, 1));
    std::reverse_copy(srcspan.begin(), srcspan.end(), retspan.begin());
    return ret;
}
 
} // namespace tcspc