basalt-core 0.0.0-rc5

package/native/core/TestDialog.cpp

@@ -0,0 +1,148 @@
+#include "TestDialog.h"
+
+#include <cstdlib>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace basalt {
+
+std::optional<int> scriptedDialogButton() {
+  static const std::optional<int> button = []() -> std::optional<int> {
+    const char *value = std::getenv("BASALT_TEST_DIALOG");
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    // A button index, and `dismiss` for the way out -- which is the last
+    // button, the one React Native's alerts and this project's share picker
+    // both put the cancelling choice in.
+    if (std::string(value) == "dismiss") {
+      return -1;
+    }
+    char *end = nullptr;
+    const long parsed = std::strtol(value, &end, 10);
+    if (end == value) {
+      return std::nullopt;
+    }
+    return static_cast<int>(parsed);
+  }();
+  return button;
+}
+
+void presentAlert(const AlertRequest &request, AlertCallback onButton) {
+  const std::optional<int> scripted = scriptedDialogButton();
+  if (!scripted.has_value()) {
+    showAlert(request, std::move(onButton));
+    return;
+  }
+
+  // The last button for `dismiss`, and the named one otherwise, clamped: a
+  // script that names a button an app did not offer should answer the nearest
+  // real one rather than an index nothing will understand.
+  const int last = request.buttons.empty() ? 0 : static_cast<int>(request.buttons.size()) - 1;
+  int button = *scripted < 0 ? last : *scripted;
+  if (button > last) {
+    button = last;
+  }
+
+  // Straight back, on this thread. The platform implementations marshal to the
+  // main thread because they have to touch a window; there is no window here,
+  // and an answer that arrives before the caller has returned is something
+  // every caller already handles -- `AsyncPromise` and the alert module's
+  // callback both settle whenever they are told to.
+  onButton(button, request.defaultText);
+}
+
+std::optional<int> scriptedMenuChoice() {
+  static const std::optional<int> choice = []() -> std::optional<int> {
+    const char *value = std::getenv("BASALT_TEST_MENU");
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    if (std::string(value) == "dismiss") {
+      return -1;
+    }
+    char *end = nullptr;
+    const long parsed = std::strtol(value, &end, 10);
+    if (end == value) {
+      return std::nullopt;
+    }
+    return static_cast<int>(parsed);
+  }();
+  return choice;
+}
+
+void presentMenu(const MenuRequest &request, MenuCallback onChosen) {
+  const std::optional<int> scripted = scriptedMenuChoice();
+  if (!scripted.has_value()) {
+    showMenu(request, std::move(onChosen));
+    return;
+  }
+
+  // Out of range answers as a dismissal rather than being clamped, which is the
+  // opposite of what presentAlert does with a button. A menu's entries are not
+  // interchangeable -- picking the nearest one would run something the script
+  // did not ask for -- whereas an alert's last button is always the way out.
+  const int last = static_cast<int>(request.entries.size()) - 1;
+  const int index = (*scripted < 0 || *scripted > last) ? -1 : *scripted;
+  onChosen(index);
+}
+
+std::optional<std::vector<std::string>> scriptedFileDialogPaths() {
+  static const std::optional<std::vector<std::string>> paths =
+      []() -> std::optional<std::vector<std::string>> {
+    const char *value = std::getenv("BASALT_TEST_FILE_DIALOG");
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    const std::string spec(value);
+    if (spec == "cancel") {
+      return std::vector<std::string>{};
+    }
+    // `;` on Windows, where a path starts "C:\\" and splitting on a colon
+    // would cut every path in two.
+#ifdef _WIN32
+    const char separator = ';';
+#else
+    const char separator = ':';
+#endif
+    std::vector<std::string> parsed;
+    size_t start = 0;
+    while (start <= spec.size()) {
+      const size_t next = spec.find(separator, start);
+      const std::string part =
+          spec.substr(start, next == std::string::npos ? std::string::npos : next - start);
+      if (!part.empty()) {
+        parsed.push_back(part);
+      }
+      if (next == std::string::npos) {
+        break;
+      }
+      start = next + 1;
+    }
+    return parsed;
+  }();
+  return paths;
+}
+
+void presentFileDialog(const FileDialogRequest &request, FileDialogCallback onDone) {
+  const std::optional<std::vector<std::string>> scripted = scriptedFileDialogPaths();
+  if (!scripted.has_value()) {
+    showFileDialog(request, std::move(onDone));
+    return;
+  }
+
+  // An empty list is `cancel`, which is the distinction the whole result shape
+  // exists to keep: "nothing was chosen" and "the person pressed Cancel" are
+  // not the same answer.
+  const bool canceled = scripted->empty();
+  std::vector<std::string> paths = *scripted;
+  // A save and a folder are one path however many the script named, which is
+  // what the platform dialogs enforce and what an app is entitled to assume.
+  if (!canceled && request.kind != FileDialogRequest::Kind::OpenFile && paths.size() > 1) {
+    paths.resize(1);
+  }
+  onDone(canceled, paths);
+}
+
+} // namespace basalt

package/native/core/TestDialog.h

@@ -0,0 +1,96 @@
+// Answering a modal dialog without showing one.
+//
+// The same escape hatch `BASALT_TEST_TAP` is, for the same reason and with the
+// same limits. A modal dialog is the one piece of interface an automated run
+// cannot get past: there is nobody to press a button, the window system will
+// not synthesise a press into a sheet, and on macOS a sheet that is up stops
+// `[NSApp terminate:]` outright -- so a run that shows one hangs until it is
+// killed.
+//
+// ## Why not drive the real dialog
+//
+// Because that is where the flakiness lives, and the platforms say so
+// themselves. Apple's own mechanism for this in UI tests,
+// `addUIInterruptionMonitor`, is documented as not firing on recent iOS
+// versions, and the workaround people reach for -- pressing the button through
+// SpringBoard -- is widely reported as flaky; Apple's own advice for permission
+// dialogs is to pre-grant them through launch arguments rather than to press
+// anything. Detox, which is the closest thing React Native has to a house
+// end-to-end runner, states the principle outright: gray box rather than black
+// box, monitor the app from the inside, because that is what fights flakiness
+// at the core.
+//
+// Driving it from outside is also not available here. AT-SPI on Linux, the
+// Accessibility API on macOS and UI Automation on Windows can each press a
+// button in a dialog, and each needs a permission or a session an automated run
+// does not have -- which is the same wall `BASALT_TEST_TAP` exists because of.
+//
+// ## What this skips, exactly
+//
+// The dialog's presentation and nothing else. The request is built by the same
+// module from the same JavaScript, the answer travels back through the same
+// callback on the same thread, and every line above the platform runs. What
+// goes untested is that the toolkit can put a dialog on screen and get a press
+// out of it, which is the same thing every other instrument in this project
+// leaves to a person.
+
+#pragma once
+
+#include "PlatformServices.h"
+
+#include <vector>
+
+#include <optional>
+
+namespace basalt {
+
+// The button index BASALT_TEST_DIALOG names, or nothing when it is unset.
+//
+// Read once and cached: an environment variable cannot change under a running
+// process, and this is consulted on a path that runs whenever an app asks a
+// question.
+std::optional<int> scriptedDialogButton();
+
+// `showAlert`, or the scripted answer when there is one.
+//
+// Everything that would put a modal dialog on screen goes through here rather
+// than calling the platform directly, so the instrument covers the share
+// picker's fallback as well as `Alert.alert` -- and covers them by *running*
+// them: a scripted "Copy" still copies, because only the presentation is
+// skipped.
+//
+// `dismiss` answers with the last button, which is where React Native's alerts
+// and this project's share picker both put the cancelling choice.
+void presentAlert(const AlertRequest &request, AlertCallback onButton);
+
+// Which entry BASALT_TEST_MENU names, or nothing when it is unset. `dismiss`
+// is -1, which is what closing a menu without choosing reports.
+//
+// A popup menu is the second thing an automated run cannot get past, and for a
+// sharper reason than a dialog: on macOS `popUpMenuPositioningItem` runs the
+// menu's own tracking loop on the main thread, so a menu nobody dismisses
+// stops the process where it stands.
+std::optional<int> scriptedMenuChoice();
+
+// `showMenu`, or the scripted answer when there is one. Everything that would
+// put a popup menu on screen goes through here rather than calling the platform
+// directly, for the same reason `presentAlert` exists.
+void presentMenu(const MenuRequest &request, MenuCallback onChosen);
+
+// What BASALT_TEST_FILE_DIALOG names, or nothing when it is unset.
+//
+// `cancel` is the person pressing Cancel. Anything else is a list of paths
+// separated by the platform's path separator -- `:` everywhere but Windows,
+// where it is `;`, because a Windows path has a colon two characters in.
+//
+// A file dialog is the third thing an automated run cannot get past, and the
+// one with the most to prove afterwards: what an app does with a path is the
+// interesting part, and it cannot be reached at all without one.
+std::optional<std::vector<std::string>> scriptedFileDialogPaths();
+
+// `showFileDialog`, or the scripted answer when there is one. Everything that
+// would put a file dialog on screen goes through here, for the same reason
+// `presentAlert` exists.
+void presentFileDialog(const FileDialogRequest &request, FileDialogCallback onDone);
+
+} // namespace basalt

package/native/core/TestKeys.cpp

@@ -0,0 +1,78 @@
+#include "TestKeys.h"
+
+#include <cstdlib>
+#include <string>
+#include <vector>
+
+namespace basalt {
+namespace {
+
+std::vector<std::string> split(const std::string &text, char separator) {
+  std::vector<std::string> parts;
+  std::string current;
+  for (const char character : text) {
+    if (character == separator) {
+      parts.push_back(current);
+      current.clear();
+      continue;
+    }
+    current += character;
+  }
+  parts.push_back(current);
+  return parts;
+}
+
+} // namespace
+
+KeyCombination parseKeyPress(const std::string &spec) {
+  KeyCombination pressed;
+  if (spec.empty()) {
+    return pressed;
+  }
+
+  // The key first, then modifiers. Split on `+` from the left and take the first
+  // piece as the key, so a literal `+` as the key is `"+"` or `"++shift"` -- the
+  // first piece being empty is the one case where an empty piece means something.
+  const std::vector<std::string> pieces = split(spec, '+');
+  pressed.key = pieces.front();
+  for (size_t i = 1; i < pieces.size(); i++) {
+    const std::string &modifier = pieces[i];
+    if (modifier == "alt") {
+      pressed.modifiers.alt = true;
+    } else if (modifier == "ctrl") {
+      pressed.modifiers.ctrl = true;
+    } else if (modifier == "meta") {
+      pressed.modifiers.meta = true;
+    } else if (modifier == "shift") {
+      pressed.modifiers.shift = true;
+    } else if (modifier.empty() && pressed.key.empty()) {
+      // `"++shift"`: the key is a literal plus, and this empty piece is it.
+      pressed.key = "+";
+    }
+    // Anything else is ignored rather than refused. A typo in a modifier name
+    // gives a combination that matches nothing, which the scenario reports as a
+    // shortcut that did not fire -- and that is the honest symptom of a typo.
+  }
+  return pressed;
+}
+
+std::vector<KeyCombination> scriptedKeyPresses() {
+  const char *value = std::getenv(kTestKeyVar);
+  if (value == nullptr || *value == '\0') {
+    return {};
+  }
+  std::vector<KeyCombination> presses;
+  for (const std::string &spec : split(std::string(value), ';')) {
+    if (spec.empty()) {
+      continue;
+    }
+    KeyCombination pressed = parseKeyPress(spec);
+    if (pressed.key.empty()) {
+      continue;
+    }
+    presses.push_back(std::move(pressed));
+  }
+  return presses;
+}
+
+} // namespace basalt

package/native/core/TestKeys.h

@@ -0,0 +1,50 @@
+// BASALT_TEST_KEY: press a key, without a keyboard.
+//
+// A real key press needs a window the display server considers focused, which an
+// automated run does not reliably have on any of the three desktops -- the same
+// reason `BASALT_TEST_TAP` exists and enters below the toolkit. So this enters
+// after the platform mapping: it builds a `KeyCombination` directly and hands it
+// to the host's own delivery, which is everything a real press does except the
+// `NSEvent`, keyval or `WM_KEYDOWN` translation.
+//
+// **What it therefore does not test** is that translation, which is the half most
+// likely to be wrong -- the three tables are each other's mirror and each one is
+// unit-tested in its own host instead. Worth stating plainly because a scenario
+// that passes here says the registry, the focus path and the round trip to
+// JavaScript work, and says nothing about whether pressing the left arrow
+// produces "ArrowLeft".
+//
+// ## The syntax
+//
+//     BASALT_TEST_KEY="z+meta;ArrowLeft;m;A+shift"
+//
+// Presses separated by `;`, a key and its modifiers separated by `+`. The key is
+// a W3C name and is taken literally, so `+` as a key is spelt by putting it
+// first. Modifiers are `alt`, `ctrl`, `meta` and `shift`.
+//
+// Parsed here, once, because three hosts parsing it is three chances to disagree
+// about what `z+meta` means -- and disagreeing quietly, since the wrong answer is
+// a combination that matches nothing and a scenario that reports a shortcut as
+// not firing.
+
+#pragma once
+
+#include "KeyEvents.h"
+
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+inline constexpr const char *kTestKeyVar = "BASALT_TEST_KEY";
+
+// The presses `BASALT_TEST_KEY` asks for, in order, or empty when it is unset.
+// An entry with no key is skipped rather than refused: one malformed press should
+// not lose the rest of a scripted sequence.
+std::vector<KeyCombination> scriptedKeyPresses();
+
+// The parser, exposed for its tests. `spec` is one press -- `"z+meta"` -- and the
+// result has an empty key when it could not be read.
+KeyCombination parseKeyPress(const std::string &spec);
+
+} // namespace basalt

package/native/core/TestQuitFile.cpp

@@ -0,0 +1,33 @@
+#include "TestQuitFile.h"
+
+#include <cstdlib>
+#include <filesystem>
+#include <optional>
+#include <string>
+
+namespace basalt {
+
+std::optional<std::string> testQuitFilePath() {
+  static const std::optional<std::string> path = []() -> std::optional<std::string> {
+    const char *value = std::getenv(kTestQuitFileVar);
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    return std::string(value);
+  }();
+  return path;
+}
+
+bool testQuitFileAppeared() {
+  const std::optional<std::string> path = testQuitFilePath();
+  if (!path.has_value()) {
+    return false;
+  }
+  // The non-throwing overload. This runs on a timer on the UI thread, and a
+  // permission error or a vanished parent directory is a reason to keep waiting
+  // rather than to terminate the process from inside a timer callback.
+  std::error_code ignored;
+  return std::filesystem::exists(*path, ignored);
+}
+
+} // namespace basalt

package/native/core/TestQuitFile.h

@@ -0,0 +1,60 @@
+// Quitting, gracefully, at a moment the harness chooses.
+//
+// `BASALT_QUIT_AFTER_MS` is the other way out, and it is decided before the
+// process starts. That is fine for a scenario whose length is known and wrong
+// for one whose length is not: the Fast Refresh scenario waits for an edit to
+// reach the window, which takes a second on a warm laptop and up to two and a
+// half minutes on a cold CI machine, so no single budget is both quick and
+// safe. It used a signal instead -- and signals are not portable. Windows has
+// no SIGTERM, `TerminateProcess` cannot be handled, and every host writes its
+// widget tree on the way out, so a killed host on Windows failed the assertion
+// that reads that tree whether or not the thing under test had worked.
+//
+// So: `BASALT_TEST_QUIT_FILE=<path>`, and the host quits as soon as <path>
+// exists, through exactly the shutdown `BASALT_QUIT_AFTER_MS` uses. The harness
+// creates the file when it has what it came for. Nothing is read from the file
+// and it may be empty; its existence is the whole message, which is why there
+// is no race worth worrying about between writing it and seeing it.
+//
+// Not refusable, for the reason the timed quit is not: this is the harness
+// ending the run rather than a person closing a window, and an app that
+// intercepts its own close would otherwise refuse the harness and hang. The
+// scenario for *that* feature is exactly such an app.
+//
+// Polled rather than watched. A file watcher is three different APIs across
+// these hosts and each has its own failure mode on network and virtual
+// filesystems; a quarter-second poll on a timer each host already runs costs
+// nothing measurable and cannot fail to be delivered.
+
+#pragma once
+
+#include <optional>
+#include <string>
+
+namespace basalt {
+
+// One spelling, in one place. Three hosts reading the variable by name is three
+// chances to typo it, and a typo here does not fail: the host simply never
+// quits, and the scenario reports a timeout somewhere unrelated.
+inline constexpr const char *kTestQuitFileVar = "BASALT_TEST_QUIT_FILE";
+
+// How often to look. Small enough that the wait is not noticeable next to the
+// process teardown that follows it, large enough to be free.
+inline constexpr unsigned kTestQuitFilePollMs = 250;
+
+// The line all three hosts log when it fires, so that three transcripts read
+// the same way. `BASALT_QUIT_AFTER_MS elapsed; quitting` had to be retrofitted
+// onto Windows after a scenario asserted on a string only two hosts printed;
+// this starts out shared instead.
+inline constexpr const char *kTestQuitFileMessage = "BASALT_TEST_QUIT_FILE appeared; quitting";
+
+// The path the instrument was pointed at, or nothing when it is off. Read once:
+// the environment does not change under a running process, and each host calls
+// this on a timer.
+std::optional<std::string> testQuitFilePath();
+
+// Whether that file exists now. False when the instrument is off, so a host can
+// call it without checking first.
+bool testQuitFileAppeared();
+
+} // namespace basalt

package/native/core/TestSettle.h

@@ -0,0 +1,192 @@
+// Quitting when there is nothing left to wait for, rather than on a guess.
+//
+// `BASALT_QUIT_AFTER_MS` is a budget chosen before the process starts, and it
+// has to be long enough for the slowest machine that will ever run it. So every
+// scenario waits out the worst case on every machine: `Image.getSize` asks for
+// three seconds and takes 3.7 of them, of which about 0.7 is real work.
+//
+// Two problems, and the smaller one is the time. The larger is that every such
+// budget is a latent flake -- "should be long enough" is a guess that a loaded
+// CI machine eventually falsifies, and when it does the scenario fails for a
+// reason that has nothing to do with what it tests. One of those is already in
+// docs/backlog/testing.md.
+//
+// `BASALT_QUIT_WHEN_SETTLED=<ms>` replaces the guess with a fact. The host quits
+// <ms> after it has settled, where settled means:
+//
+//   - the first mount has been applied -- React produced a tree and the host
+//     put it on screen. Recorded in MountingWalk::applyMutations, which is the
+//     one place all three hosts mount through, so this is one code site rather
+//     than three.
+//   - any scripted input has been delivered. Each host schedules its own and
+//     knows the total, and says so through noteScriptedInputEndsInMs.
+//
+// `BASALT_QUIT_AFTER_MS` stays as the backstop, so nothing gets *slower* and a
+// host that never settles still ends. The two are complementary: one is the
+// ceiling, this is the actual duration.
+//
+// The <ms> is a settle rather than a deadline, and it is small -- a few hundred
+// milliseconds for React's next commit and the frame that draws it. It is still
+// a guess, but it is a guess about one round trip instead of about a whole
+// scenario, and quitting too early fails loudly: every scenario that opts in
+// asserts on the dumped tree, so a tree that is not there yet is a failure and
+// not a false pass. That direction is the whole reason this is safe to do.
+
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdlib>
+#include <optional>
+#include <string>
+
+namespace basalt {
+
+inline constexpr const char *kQuitWhenSettledVar = "BASALT_QUIT_WHEN_SETTLED";
+
+// One line, shared, for the reason core/TestQuitFile.h gives: three hosts
+// spelling it themselves is three chances to differ, and a scenario that asserts
+// on a string only two of them print fails on the third for no reason.
+inline constexpr const char *kQuitWhenSettledMessage = "BASALT_QUIT_WHEN_SETTLED: settled; quitting";
+
+inline long long testNowMs() {
+  return std::chrono::duration_cast<std::chrono::milliseconds>(
+             std::chrono::steady_clock::now().time_since_epoch())
+      .count();
+}
+
+// Zero means "not yet". A steady clock could in principle read zero at process
+// start, which would make the first mount look like it had never happened, so
+// the stored value is never allowed to be.
+inline std::atomic<long long> &firstMountAtMsRef() {
+  static std::atomic<long long> value{0};
+  return value;
+}
+
+// When the scripted input finishes, as an absolute time on the same clock. Zero
+// when there is none, which is the common case.
+inline std::atomic<long long> &scriptedInputEndsAtMsRef() {
+  static std::atomic<long long> value{0};
+  return value;
+}
+
+// Called from MountingWalk::applyMutations, on every transaction; only the first
+// is kept. Cheap enough to sit on that path unconditionally -- one relaxed load
+// and, once, one compare-exchange.
+inline void noteMountApplied() {
+  if (firstMountAtMsRef().load(std::memory_order_relaxed) != 0) {
+    return;
+  }
+  long long expected = 0;
+  const long long now = testNowMs();
+  firstMountAtMsRef().compare_exchange_strong(expected, now == 0 ? 1 : now);
+}
+
+// Called by a host once, after it has scheduled whatever BASALT_TEST_TAP and its
+// siblings asked for. `delayMs` is the total schedule, which is what each host
+// already computes to lay the timers out.
+inline void noteScriptedInputEndsInMs(long long delayMs) {
+  scriptedInputEndsAtMsRef().store(testNowMs() + (delayMs > 0 ? delayMs : 0));
+}
+
+// Whether anything was asked to be delivered *into* the app. The hosts lay their
+// scripted input out starting 1500ms in -- a tap needs a window to land on --
+// and they report that total whether or not any of it was asked for, so without
+// this a scenario that only mounts would wait out a schedule that is empty. It
+// measured 2.96s against a 3s budget, which is to say no saving at all on
+// exactly the scenarios this should help most.
+//
+// **A new instrument that a host puts on its scripted timer belongs in this
+// list.** Left out, its scenario settles before the input lands -- which fails
+// rather than passes, because everything that opts in asserts on the mounted
+// tree, but it fails for a reason a long way from the change.
+//
+// Scheduled, not merely test-related. `BASALT_TEST_MENU` and
+// `BASALT_TEST_DIALOG` are deliberately absent: they *answer* something when it
+// appears, from core/TestDialog.cpp, and are never laid out on a host's timer --
+// so they say nothing about when a schedule ends. Every scenario that uses them
+// also drives the thing that shows the menu or the dialog, and that instrument
+// is in this list. Including them was the first version, and the check below
+// caught it: a list of "instruments to do with input" is not the same as a list
+// of "instruments that delay the schedule", and only the second is what
+// scriptedInputEndsAtMs needs.
+//
+// scripts/test_harness.py holds this against what the three host mains actually
+// read, in both directions -- an instrument they schedule and this omits, and an
+// entry here that no host knows about, which is what a rename leaves behind.
+// native/tests/test_settle.cpp checks the contents.
+inline const char *const *scriptedInputVars(std::size_t &count) {
+  static const char *const vars[] = {
+      "BASALT_TEST_TAP",
+      "BASALT_TEST_SECONDARY_TAP",
+      "BASALT_TEST_CLICK",
+      "BASALT_TEST_HOVER",
+      "BASALT_TEST_SCROLL",
+      "BASALT_TEST_FOCUS",
+      "BASALT_TEST_KEY",
+      "BASALT_TEST_TYPE",
+      "BASALT_TEST_DRAG",
+      "BASALT_TEST_DROP",
+      "BASALT_TEST_QUIT",
+      "BASALT_TEST_CLOSE_WINDOW",
+  };
+  count = sizeof(vars) / sizeof(vars[0]);
+  return vars;
+}
+
+inline bool anyScriptedInputRequested() {
+  static const bool any = []() {
+    std::size_t count = 0;
+    const char *const *vars = scriptedInputVars(count);
+    for (std::size_t i = 0; i < count; i++) {
+      const char *value = std::getenv(vars[i]);
+      if (value != nullptr && *value != '\0') {
+        return true;
+      }
+    }
+    return false;
+  }();
+  return any;
+}
+
+inline std::optional<unsigned> quitWhenSettledMs() {
+  static const std::optional<unsigned> ms = []() -> std::optional<unsigned> {
+    const char *value = std::getenv(kQuitWhenSettledVar);
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    char *end = nullptr;
+    const unsigned long parsed = std::strtoul(value, &end, 10);
+    if (end == value) {
+      return std::nullopt;
+    }
+    return static_cast<unsigned>(parsed);
+  }();
+  return ms;
+}
+
+// Whether everything worth waiting for has happened, and the settle has passed.
+inline bool hasSettled() {
+  const std::optional<unsigned> settle = quitWhenSettledMs();
+  if (!settle.has_value()) {
+    return false;
+  }
+  const long long mounted = firstMountAtMsRef().load();
+  if (mounted == 0) {
+    return false;
+  }
+  // The later of the two, because a scenario that taps needs the tap delivered
+  // and a scenario that does not still needs its tree. Taking the maximum makes
+  // the two cases one expression rather than a branch that can be got wrong.
+  //
+  // Only when input was actually asked for. The hosts report their schedule
+  // total unconditionally, and that total is never zero -- it starts at 1500ms
+  // so a tap has a window to land on -- so an empty schedule would otherwise be
+  // waited out by every scenario that just mounts.
+  const long long scripted = anyScriptedInputRequested() ? scriptedInputEndsAtMsRef().load() : 0;
+  const long long ready = mounted > scripted ? mounted : scripted;
+  return testNowMs() - ready >= static_cast<long long>(*settle);
+}
+
+} // namespace basalt