Run History

A run started from the controller shows in the tree as it goes: a run row under each test, its status, its times, its endpoints, and the results behind it in the Details dialog. A run made from the command line, the CI snapshot of the previous page, a suite run by a script, a test run by an AI agent, leaves logs and nothing else: there is no tree to show it in. The run history closes that gap. Every run writes, next to its logs, a file that holds what the controller would have shown, and Add Item opens that file the way it opens a batch: the run's items appear in the tree with a run row per test, statuses, times, endpoints and results included, as if the run had been started here.

The file goes into a Run_History folder next to the Logs folder of the run, named after the run's root and the moment it started, Batch__regression__2026-09-13__14-23-45.647.orcraft-run for the regression snapshot. The root is whatever was run, a batch, a suite, a group or a single test, and the file is written as the run goes, record by record: the root and its source file first, then each test's process as it starts, its progress and results as they arrive, its outcome when it ends, and the root's outcome last. A run that is killed leaves a readable file, and the tests it never finished come into the tree as stopped.

Like a session file, the history does not copy the suites. It records where the root came from, the batch.py of the snapshot here, and the controller loads the items from that source when the file is added, so the tree shows the tests as they are, with the run's rows beneath them. The file has to be added on a machine that can reach that source.

The history of the snapshot run

The python ci_run.py run of the previous page wrote its history beside the snapshot's logs:

C:\orcraft\ci\regression\
  Logs\
  Run_History\
    Batch__regression__2026-09-13__14-23-45.647.orcraft-run

The file holds everything the controller needs to show the run as if it had made it: the batch file the run started from, and for every test process its place in the batch, the endpoints it worked on, the values it ran with, the log it wrote, its cases, flows and steps with their statuses and results, and its outcome and times. Nothing in it is meant to be read by hand: the file exists to be opened by the controller.

Adding the history to the tree

Start a new session and click Add Item. The file dialog lists .orcraft-run files alongside Python files; pick the history from the Run_History folder. The controller loads the batch from the source the file names, and attaches the recorded runs:

The batch row carries a History badge: it was added from a history file, not from a batch file picked by hand. Its tests carry the CI badge as on the previous page, since they come from the snapshot, and each of them holds a Test Run row with the History badge of its own, the sign that the run was recorded elsewhere and brought in. The row reads exactly what the run produced: the status, the endpoints, the start and finish times, the elapsed time. Selecting it shows the test's log in the Log frame, read from the log file the history names, and the Details dialog lays out its cases, flows and steps as for any run. The batch, the suite and the groups tally these runs like the runs they make themselves.

The values the run used became the test's plan. Open a test's panel and the fields show what the snapshot ran with, in blue as planned values, so a rerun from here runs the same configuration; the run row's own panel shows the same values as the run's.

Attaching to an item already in the session

A snapshot that runs every night produces a history every night, and the second one belongs with the first. Click Add Item again and pick the same file. The controller finds that the run's batch is already in the session, the same batch.py, and asks:

Attach to Existing puts the recorded runs under the tests that are already there. Each test gets one more run row with the History badge, and its earlier row is dimmed as superseded, exactly as when a test is run twice from the controller. The batch keeps the plan it has; only runs are added:

Add Separately does what the first add did: a second batch node with the History badge, its own tests and its own rows, for a run that should be looked at on its own. The question is asked every time a match exists and nothing is remembered, so one night's run can be attached and the next one kept aside. When nothing in the session matches the file, the run is added as a node without a question, and when the item is in the session more than once, the question lists them by their path, label and the runs they hold; picking one highlights it in the tree, so the row meant is never in doubt.

The match is made on the source file, at any depth of the tree: a history of a group run finds that group inside a loaded suite as readily as a batch finds a batch. That is also how a test removed from the tree by mistake gets its runs back: reload the suite, add the history, attach.

Narrowing to the history

Runs from files and runs made here sit side by side, and the row above the tree tells them apart. An H toggle appears beside the CI toggle while the session holds history runs. Click it to see only those runs and the tests holding them:

The toggle combines with the CI toggle and the status chips, so H and Fail together show the recorded runs that failed. A second click turns it off, and the whole tree is back.

Histories the controller writes

The controller runs each test in a process of its own, and that process writes the history of that one test, Test__Hello_World__...orcraft-run, like any framework run. A run over a group, a suite, a batch, the session or a selection is more than its tests, so the controller writes the whole of it too, next to its own Logs:

C:\orcraft\Run_History\
  GUI__Group__Intro__2026-09-13__14-27-12.787.orcraft-run
  Test__Hello_World__2026-09-13__14-27-13.430.orcraft-run
  GUI__Suite__Orcraft_Tutorial__2026-09-13__14-27-22.140.orcraft-run
  GUI__Test__Hello_World__2026-09-13__14-27-22.266.orcraft-run
  Test__Hello_World__2026-09-13__14-27-22.808.orcraft-run
  Test__Hello_World__2026-09-13__14-27-22.928.orcraft-run

The GUI prefix marks a file the controller wrote. Running the Intro group from its panel made the first pair: the controller's file with the group as root and one leaf for Hello World, and the test process's own file beside it. A run over the session or over a selection spans several top-level items, and none of them is the root of the others, so such a run makes one file per top-level item its tests belong to. The second set came from a selection of the tutorial suite's Hello World and the Hello World test item added on its own: one file with the suite as root, one with the test item as root, and the two test processes' files. Each file opens on its own, and a fan-out run records one leaf per permutation, as the CI run does.

These files are what makes a run portable. A run made on one controller can be added to another, a run from a session that was replaced can be brought into the new one, and an AI agent that ran a suite from a script hands over its history for the lab to look at in the tree.

A run from another machine

The paths inside a history file are the machine's that wrote it: the batch file the run started from and the logs it wrote. Opened on another machine, the controller looks for each of them at the recorded path first, and then at the same place below the folder that holds Run_History. A run writes Logs and Run_History side by side in its working folder, so a working folder that travels whole keeps the logs where the controller finds them, and every run row opens its log from the copy. The batch file is found the same way when the working folder holds it too: a pipeline that checks the snapshot out inside the run's working folder, or copies it there, and publishes that folder as its artifact, produces a history that opens anywhere without a question. Add the .orcraft-run file from the unzipped artifact as before, and the runs show as they do for a run made here, with the pipeline's endpoints, times and results.

A pipeline laid out otherwise still works. When the batch file is neither at the recorded path nor below the history's folder, the controller says so, names the recorded path, and asks where the file is on this machine with a file dialog; point it at your copy of the batch, suite, group or test file, and the run opens from it. From then on the item is yours: it no longer depends on the folder the run used.

History runs in sessions

A history run is an ordinary run once it is in the tree. Saving the session records the rows with their badges, and loading it brings them back marked as they were, together with the H toggle. Clean Up removes superseded history rows like any other, Clear removes them all, and a node added from a history file is reloaded, unplanned or removed like a node added from a batch file.

The snapshot pointed back at two repositories, and the controller keeps an eye on where each of them stands. The next page, Git Status Frame, shows the panel that does so.