Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/src/Progmasoft/Runner/Process.hpp
diff options
context:
space:
mode:
authorLeitwolf2026-10-24 19:03:40 +0300
committerGitHub2026-10-24 19:03:40 +0300
commit4f1c759cffcb14bd6511e1d7c5fbace682e24f2d (patch)
tree415fe5d48a5b48650bba3747beaf245d727c4f61 /src/Progmasoft/Runner/Process.hpp
parent83c6fc3ac13abe83fa39f7b5f8559ccaf4412233 (diff)
parent622188f9c08e4af35941c146979883ed4882410e (diff)
downloadcatch3-4f1c759cffcb14bd6511e1d7c5fbace682e24f2d.tar.gz
Merge pull request #15 from Progmasoft/feature/catch3-runner
Replace Catch2's runner with the Catch3 runner
Diffstat (limited to 'src/Progmasoft/Runner/Process.hpp')
-rw-r--r--src/Progmasoft/Runner/Process.hpp262
1 files changed, 262 insertions, 0 deletions
diff --git a/src/Progmasoft/Runner/Process.hpp b/src/Progmasoft/Runner/Process.hpp
new file mode 100644
index 00000000..3d6eba0c
--- /dev/null
+++ b/src/Progmasoft/Runner/Process.hpp
@@ -0,0 +1,262 @@
+// Copyright (c) 2026 Progmasoft.
+// SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-1.1
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <filesystem>
+#include <memory>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+#include "Expected.hpp"
+
+namespace Progmasoft::Catch3::Runner
+{
+ /// How a process ended.
+ struct ExitStatus final
+ {
+ enum class Kind : std::uint8_t
+ {
+ /// It returned from `main` or called `exit` with `code`.
+ kExited,
+ /// A signal ended it (POSIX); `code` is the signal number.
+ kSignaled,
+ /// It ended with a structured exception (Windows); `code` is the
+ /// exception code, such as 0xC0000005 for an access violation.
+ kException,
+ };
+
+ Kind kind = Kind::kExited;
+ std::int64_t code = 0;
+
+ [[nodiscard]] bool
+ Succeeded() const noexcept
+ {
+ return kind == Kind::kExited && code == 0;
+ }
+
+ /// Whether the process died rather than exiting.
+ [[nodiscard]] bool
+ Crashed() const noexcept
+ {
+ return kind != Kind::kExited;
+ }
+
+ /// A description such as "exit code 3", "signal 11 (SIGSEGV)" or
+ /// "exception 0xC0000005 (access violation)".
+ [[nodiscard]] std::string
+ Describe() const;
+ };
+
+ /// The end of a pipe this process reads from.
+ class PipeReader final
+ {
+ public:
+ PipeReader() = default;
+ explicit PipeReader(std::intptr_t handle) noexcept
+ : handle_{ handle }
+ {}
+ PipeReader(const PipeReader &) = delete;
+ PipeReader &
+ operator=(const PipeReader &) = delete;
+ PipeReader(PipeReader &&other) noexcept;
+ PipeReader &
+ operator=(PipeReader &&other) noexcept;
+ ~PipeReader();
+
+ /// Reads at most `size` bytes. Returns the number read, 0 at the end
+ /// of the stream and -1 on an error.
+ [[nodiscard]] std::int64_t
+ Read(char *buffer, std::size_t size) noexcept;
+
+ void
+ Close() noexcept;
+
+ [[nodiscard]] bool
+ IsOpen() const noexcept;
+
+ private:
+ std::intptr_t handle_ = -1;
+ };
+
+ /// The end of a pipe this process writes to.
+ class PipeWriter final
+ {
+ public:
+ PipeWriter() = default;
+ explicit PipeWriter(std::intptr_t handle) noexcept
+ : handle_{ handle }
+ {}
+ PipeWriter(const PipeWriter &) = delete;
+ PipeWriter &
+ operator=(const PipeWriter &) = delete;
+ PipeWriter(PipeWriter &&other) noexcept;
+ PipeWriter &
+ operator=(PipeWriter &&other) noexcept;
+ ~PipeWriter();
+
+ /// Writes all of `data`, or reports why it could not.
+ Status
+ Write(std::string_view data) noexcept;
+
+ void
+ Close() noexcept;
+
+ [[nodiscard]] bool
+ IsOpen() const noexcept;
+
+ private:
+ std::intptr_t handle_ = -1;
+ };
+
+ /// What to start, and how.
+ struct ChildOptions final
+ {
+ /// The program and its arguments. The program is a path; it is not
+ /// looked up on `PATH` unless `searchPath` is set.
+ std::vector<std::string> arguments;
+ /// Variables added to, or replacing, those of this process.
+ std::vector<std::pair<std::string, std::string>> environment;
+ /// The working directory; empty keeps the current one.
+ std::filesystem::path workingDirectory;
+ bool searchPath = false;
+ };
+
+ /// A child process with its standard streams connected to pipes.
+ ///
+ /// The child and every process it starts in turn form one group (a job
+ /// object on Windows, a process group elsewhere), so `Kill` ends a test
+ /// together with the helpers it spawned. Pipes are not inherited by
+ /// any other child, so the end of a stream is seen as soon as its
+ /// process is gone.
+ class ChildProcess final
+ {
+ public:
+ ChildProcess(const ChildProcess &) = delete;
+ ChildProcess &
+ operator=(const ChildProcess &) = delete;
+ ~ChildProcess();
+
+ [[nodiscard]] static Expected<std::unique_ptr<ChildProcess>>
+ Start(const ChildOptions &options);
+
+ /// The child's standard input.
+ [[nodiscard]] PipeWriter &
+ Input() noexcept
+ {
+ return input_;
+ }
+
+ /// The child's standard output.
+ [[nodiscard]] PipeReader &
+ Output() noexcept
+ {
+ return output_;
+ }
+
+ /// The child's standard error.
+ [[nodiscard]] PipeReader &
+ Errors() noexcept
+ {
+ return errors_;
+ }
+
+ /// Ends the child and every process it started. Safe to call more
+ /// than once and after the child ended.
+ void
+ Kill() noexcept;
+
+ /// Waits for the child to end.
+ [[nodiscard]] ExitStatus
+ Wait() noexcept;
+
+ /// Waits at most `timeout`; nothing when the child still runs.
+ [[nodiscard]] std::optional<ExitStatus>
+ WaitFor(std::chrono::milliseconds timeout) noexcept;
+
+ [[nodiscard]] std::int64_t
+ Id() const noexcept
+ {
+ return id_;
+ }
+
+ private:
+ ChildProcess() = default;
+
+ PipeWriter input_;
+ PipeReader output_;
+ PipeReader errors_;
+ std::int64_t id_ = 0;
+ std::intptr_t process_ = -1;
+ std::intptr_t group_ = -1;
+ std::optional<ExitStatus> exit_;
+ };
+
+ /// The result of a command run to completion.
+ struct CapturedRun final
+ {
+ ExitStatus status;
+ std::string output;
+ std::string errors;
+ };
+
+ /// Runs a command with no input and collects its output.
+ [[nodiscard]] Expected<CapturedRun>
+ RunAndCapture(const ChildOptions &options);
+
+ /// The two streams a worker talks to the runner over.
+ struct WorkerStreams final
+ {
+ PipeReader commands;
+ PipeWriter events;
+ };
+
+ /// Takes standard input and output of this process for the runner
+ /// protocol. Afterwards standard input reads nothing and standard output
+ /// goes to standard error, so what a test prints cannot corrupt a
+ /// message.
+ [[nodiscard]] Expected<WorkerStreams>
+ TakeStandardStreams();
+
+ /// The path of the running executable.
+ [[nodiscard]] std::filesystem::path
+ CurrentExecutable(const char *argumentZero);
+
+ /// The number of hardware threads, at least 1.
+ [[nodiscard]] unsigned
+ HardwareThreads() noexcept;
+
+ /// The value of an environment variable; empty when it is not set.
+ [[nodiscard]] std::string
+ ReadEnvironment(const char *name);
+
+ [[nodiscard]] bool
+ HasEnvironment(const char *name);
+
+ /// Whether standard output is a terminal.
+ [[nodiscard]] bool
+ IsStandardOutputTerminal() noexcept;
+
+ /// Turns on ANSI colour sequences on a Windows console; true when the
+ /// terminal shows them.
+ [[nodiscard]] bool
+ EnableTerminalColours() noexcept;
+
+ /// Keeps a crash of a worker on Windows from opening an error-reporting
+ /// dialog that would wait for a person. Elsewhere it does nothing.
+ void
+ QuietCrashReporting() noexcept;
+
+ /// The id of this process.
+ [[nodiscard]] std::int64_t
+ CurrentProcessId() noexcept;
+
+ /// Writes `text` to descriptor 2 directly, past any stream buffer or
+ /// redirection, as far as it goes; for use while the process exits.
+ void
+ WriteStandardError(std::string_view text) noexcept;
+} // namespace Progmasoft::Catch3::Runner