From 7c44e72c39a388295e98c5b57cecdedc48720db7 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 00:51:36 -0800 Subject: [PATCH] Define versioned lab state contract --- .../CommonFramework/Windows/LabStateV1.cpp | 172 ++++++++++++++++++ .../CommonFramework/Windows/LabStateV1.h | 97 ++++++++++ .../Windows/LabStateV1_Tests.cpp | 140 ++++++++++++++ .../Windows/LabStateV1_Tests.h | 20 ++ .../ComputerPrograms_UnitTestRunner.cpp | 37 ++-- SerialPrograms/cmake/SourceFiles.cmake | 4 + 6 files changed, 455 insertions(+), 15 deletions(-) create mode 100644 SerialPrograms/Source/CommonFramework/Windows/LabStateV1.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Windows/LabStateV1.h create mode 100644 SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.cpp create mode 100644 SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.h diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.cpp b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.cpp new file mode 100644 index 0000000000..fb1efd2500 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.cpp @@ -0,0 +1,172 @@ +/* Lab State V1 + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include "Common/Cpp/Json/JsonObject.h" +#include "LabStateV1.h" + +namespace PokemonAutomation{ +namespace{ + + +std::string panel_kind_name(LabStateV1::PanelKind kind){ + switch (kind){ + case LabStateV1::PanelKind::NONE: + return "none"; + case LabStateV1::PanelKind::PROGRAM: + return "program"; + case LabStateV1::PanelKind::SETTINGS: + return "settings"; + case LabStateV1::PanelKind::OTHER: + return "other"; + } + return "other"; +} + +std::string program_state_name(LabStateV1::ProgramState state){ + switch (state){ + case LabStateV1::ProgramState::NO_PROGRAM: + return "no_program"; + case LabStateV1::ProgramState::NOT_READY: + return "not_ready"; + case LabStateV1::ProgramState::STOPPED: + return "stopped"; + case LabStateV1::ProgramState::RUNNING: + return "running"; + case LabStateV1::ProgramState::STOPPING: + return "stopping"; + } + return "not_ready"; +} + +std::string action_source_name(LabStateV1::ActionSource source){ + switch (source){ + case LabStateV1::ActionSource::NONE: + return "none"; + case LabStateV1::ActionSource::UI: + return "ui"; + case LabStateV1::ActionSource::LAB: + return "lab"; + case LabStateV1::ActionSource::PROGRAM: + return "program"; + case LabStateV1::ActionSource::ERROR: + return "error"; + } + return "none"; +} + +std::string video_state_name(LabStateV1::VideoState state){ + switch (state){ + case LabStateV1::VideoState::MISSING: + return "missing"; + case LabStateV1::VideoState::STALE: + return "stale"; + case LabStateV1::VideoState::LIVE: + return "live"; + } + return "missing"; +} + +std::string signal_state_name(LabStateV1::SignalState state){ + switch (state){ + case LabStateV1::SignalState::UNKNOWN: + return "unknown"; + case LabStateV1::SignalState::OK: + return "ok"; + case LabStateV1::SignalState::BLACK: + return "black"; + case LabStateV1::SignalState::COLOR_BARS: + return "colour_bars"; + } + return "unknown"; +} + +std::string controller_state_name(LabStateV1::ControllerState state){ + switch (state){ + case LabStateV1::ControllerState::NOT_APPLICABLE: + return "not_applicable"; + case LabStateV1::ControllerState::NONE: + return "none"; + case LabStateV1::ControllerState::READY: + return "ready"; + } + return "none"; +} + +JsonValue optional_string(const std::optional& value){ + return value ? JsonValue(*value) : JsonValue(); +} + +JsonObject make_program(const LabStateV1& state){ + JsonObject transition; + transition["action"] = optional_string(state.transition_action); + transition["at"] = optional_string(state.transition_at); + transition["request_id"] = optional_string(state.transition_request_id); + transition["source"] = action_source_name(state.transition_source); + + JsonObject program; + program["last_transition"] = state.transition_source == LabStateV1::ActionSource::NONE + ? JsonValue() + : JsonValue(std::move(transition)); + program["run_id"] = optional_string(state.run_id); + program["state"] = program_state_name(state.program_state); + return program; +} + +JsonObject make_video(const LabStateV1& state){ + JsonObject video; + video["captured_at"] = optional_string(state.video_captured_at); + video["frame_seq"] = state.video_frame_seq + ? JsonValue(*state.video_frame_seq) + : JsonValue(); + video["signal"] = signal_state_name(state.video_signal); + video["state"] = video_state_name(state.video_state); + return video; +} + +JsonObject make_unknown_observation(){ + JsonObject game; + game["observed_at"] = JsonValue(); + game["value"] = "unknown"; + JsonObject screen; + screen["observed_at"] = JsonValue(); + screen["value"] = "unknown"; + + JsonObject observation; + observation["game"] = std::move(game); + observation["screen"] = std::move(screen); + return observation; +} + + +} // namespace + +std::string lab_state_json_text(const LabStateV1& state){ + JsonObject instance; + instance["id"] = state.instance_id; + instance["pid"] = state.process_id; + + JsonObject panel; + panel["id"] = state.panel_id; + panel["kind"] = panel_kind_name(state.panel_kind); + + JsonObject controller; + controller["state"] = controller_state_name(state.controller_state); + + JsonObject root; + root["controller"] = std::move(controller); + root["instance"] = std::move(instance); + root["observation"] = make_unknown_observation(); + root["panel"] = std::move(panel); + root["program"] = make_program(state); + root["schema"] = 1; + root["video"] = make_video(state); + root["written_at"] = state.written_at; + return root.dump(4); +} + + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.h b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.h new file mode 100644 index 0000000000..d50ecdcfe1 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1.h @@ -0,0 +1,97 @@ +/* Lab State V1 + * + * From: https://github.com/PokemonAutomation/ + * + * The versioned JSON state published beside the legacy Lab/state file. + * Fields the app cannot observe remain unknown/null; readers must not infer + * success from their absence. + * + */ + +#ifndef PokemonAutomation_LabStateV1_H +#define PokemonAutomation_LabStateV1_H + +#include +#include +#include + +namespace PokemonAutomation{ + + +// App-authored values in schema 1 of Lab/state.json. +struct LabStateV1{ + // The kind of panel selected in the main window. + enum class PanelKind{ + NONE, + PROGRAM, + SETTINGS, + OTHER, + }; + + // State of the selected program, including the absence of one. + enum class ProgramState{ + NO_PROGRAM, + NOT_READY, + STOPPED, + RUNNING, + STOPPING, + }; + + // Where a program state transition originated. + enum class ActionSource{ + NONE, + UI, + LAB, + PROGRAM, + ERROR, + }; + + // Whether the app is receiving frames from the video transport. + enum class VideoState{ + MISSING, + STALE, + LIVE, + }; + + // Visual signal classification, independent of transport freshness. + enum class SignalState{ + UNKNOWN, + OK, + BLACK, + COLOR_BARS, + }; + + // Whether the selected panel has a controller ready for commands. + enum class ControllerState{ + NOT_APPLICABLE, + NONE, + READY, + }; + + std::string written_at; + std::string instance_id; + uint64_t process_id = 0; + + std::string panel_id; + PanelKind panel_kind = PanelKind::NONE; + ProgramState program_state = ProgramState::NO_PROGRAM; + std::optional run_id; + + std::optional transition_action; + ActionSource transition_source = ActionSource::NONE; + std::optional transition_request_id; + std::optional transition_at; + + ControllerState controller_state = ControllerState::NOT_APPLICABLE; + VideoState video_state = VideoState::MISSING; + std::optional video_frame_seq; + std::optional video_captured_at; + SignalState video_signal = SignalState::UNKNOWN; +}; + +// Serialize one complete schema-1 state object. +std::string lab_state_json_text(const LabStateV1& state); + + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.cpp b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.cpp new file mode 100644 index 0000000000..11ace2e3d5 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.cpp @@ -0,0 +1,140 @@ +/* Lab State V1 - Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonObject.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "LabStateV1.h" +#include "LabStateV1_Tests.h" + +namespace PokemonAutomation{ +namespace{ + + +struct LabStateTestInput{ + LabStateV1 state; +}; + +struct LabStateTestExpectation{ + std::string_view json; +}; + +struct LabStateTestCase{ + std::string name; + LabStateTestInput input; + LabStateTestExpectation expectation; +}; + +class Test_LabStateV1 : public UnitTest{ +public: + explicit Test_LabStateV1(LabStateTestCase test_case) + : UnitTest(std::format("CommonFramework::LabStateV1 - {}", test_case.name)) + , m_case(std::move(test_case)) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + const JsonValue actual = parse_json(lab_state_json_text(m_case.input.state)); + const JsonValue expected = parse_json(std::string(m_case.expectation.json)); + if (actual != expected){ + return std::format( + "Expected {}, got {}", m_case.expectation.json, lab_state_json_text(m_case.input.state) + ); + } + return true; + } + +private: + LabStateTestCase m_case; +}; + +const LabStateTestCase TEST_CASES[] = { + { + .name = "observed stopped program", + .input = { + .state = { + .written_at = "2026-11-14T06:10:12.124Z", + .instance_id = "app-1", + .process_id = 4411, + .panel_id = "PokemonFRLG:AutoStory", + .panel_kind = LabStateV1::PanelKind::PROGRAM, + .program_state = LabStateV1::ProgramState::STOPPED, + .run_id = std::nullopt, + .transition_action = "stop", + .transition_source = LabStateV1::ActionSource::LAB, + .transition_request_id = "request-1", + .transition_at = "2026-11-14T06:10:10.002Z", + .controller_state = LabStateV1::ControllerState::READY, + .video_state = LabStateV1::VideoState::LIVE, + .video_frame_seq = 918274, + .video_captured_at = "2026-11-14T06:10:12.091Z", + .video_signal = LabStateV1::SignalState::UNKNOWN, + }, + }, + .expectation = { + .json = R"json({ + "schema": 1, + "written_at": "2026-11-14T06:10:12.124Z", + "instance": {"id": "app-1", "pid": 4411}, + "panel": {"id": "PokemonFRLG:AutoStory", "kind": "program"}, + "program": { + "state": "stopped", + "run_id": null, + "last_transition": { + "action": "stop", + "source": "lab", + "request_id": "request-1", + "at": "2026-11-14T06:10:10.002Z" + } + }, + "controller": {"state": "ready"}, + "video": { + "state": "live", + "frame_seq": 918274, + "captured_at": "2026-11-14T06:10:12.091Z", + "signal": "unknown" + }, + "observation": { + "game": {"value": "unknown", "observed_at": null}, + "screen": {"value": "unknown", "observed_at": null} + } + })json", + }, + }, + { + .name = "unobserved defaults", + .input = {.state = {}}, + .expectation = { + .json = R"json({ + "schema": 1, + "written_at": "", + "instance": {"id": "", "pid": 0}, + "panel": {"id": "", "kind": "none"}, + "program": {"state": "no_program", "run_id": null, "last_transition": null}, + "controller": {"state": "not_applicable"}, + "video": {"state": "missing", "frame_seq": null, "captured_at": null, "signal": "unknown"}, + "observation": { + "game": {"value": "unknown", "observed_at": null}, + "screen": {"value": "unknown", "observed_at": null} + } + })json", + }, + }, +}; + + +} // namespace + +void add_tests_LabStateV1(UnitTestDatabase& database){ + for (const LabStateTestCase& test_case : TEST_CASES){ + database.add(test_case); + } +} + + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.h b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.h new file mode 100644 index 0000000000..6f3e379121 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/Windows/LabStateV1_Tests.h @@ -0,0 +1,20 @@ +/* Lab State V1 - Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_LabStateV1_Tests_H +#define PokemonAutomation_LabStateV1_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ + + +// Add the versioned lab-state serialization tests. +void add_tests_LabStateV1(UnitTestDatabase& database); + + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp index 0bf2672c6d..318b54ec09 100644 --- a/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp +++ b/SerialPrograms/Source/ComputerPrograms/ComputerPrograms_UnitTestRunner.cpp @@ -23,6 +23,7 @@ #include "CommonFramework/ProgramStats/StatsTracking.h" #include "CommonFramework/Tools/GlobalThreadPools.h" #include "CommonFramework/Windows/LabChannel_Tests.h" +#include "CommonFramework/Windows/LabStateV1_Tests.h" #include "CommonTools/VisualDetectors/BlackBorderDetector.h" #include "CommonTools/OCR/OCR_Tests.h" @@ -47,28 +48,34 @@ namespace PokemonAutomation{ namespace ComputerPrograms{ +namespace{ + + +void add_infrastructure_tests(UnitTestDatabase& database){ + add_tests_QtEventThreadPool(database, GlobalThreadPools::computation_normal()); + add_tests_Sockets(database, GlobalThreadPools::unlimited_normal()); + add_tests_BlackBorderDetector(database); + add_tests_ListenerSet(database); + add_tests_MoveOnlyFunction(database); + SysbotBase::add_tests_SysbotBasePing(database); + SysbotBase::add_tests_SysbotBaseReceiveLine(database); + add_tests_AudioInfo(database); + add_tests_ChannelMixerMatrix(database); + add_tests_FFTStreamer(database); + add_tests_SinkPipeline(database); + add_tests_AudioFileLoader(database); + add_tests_LabChannel(database); + add_tests_LabStateV1(database); +} - - +} // namespace UnitTestDatabase make_UNIT_TESTS_ALL(){ UnitTestDatabase ret; - add_tests_QtEventThreadPool(ret, GlobalThreadPools::computation_normal()); - add_tests_Sockets(ret, GlobalThreadPools::unlimited_normal()); - add_tests_BlackBorderDetector(ret); - add_tests_ListenerSet(ret); - add_tests_MoveOnlyFunction(ret); - SysbotBase::add_tests_SysbotBasePing(ret); - SysbotBase::add_tests_SysbotBaseReceiveLine(ret); - add_tests_AudioInfo(ret); - add_tests_ChannelMixerMatrix(ret); - add_tests_FFTStreamer(ret); - add_tests_SinkPipeline(ret); - add_tests_AudioFileLoader(ret); - add_tests_LabChannel(ret); + add_infrastructure_tests(ret); OCR::add_tests(ret); Kernels::add_tests(ret); Pokemon::add_tests_AutoStorySelect(ret); diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index 66bbc02b7b..b71781fd58 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -801,6 +801,10 @@ file(GLOB LIBRARY_SOURCES Source/CommonFramework/Windows/LabChannel_Tests.h Source/CommonFramework/Windows/LabRequest.cpp Source/CommonFramework/Windows/LabRequest.h + Source/CommonFramework/Windows/LabStateV1.cpp + Source/CommonFramework/Windows/LabStateV1.h + Source/CommonFramework/Windows/LabStateV1_Tests.cpp + Source/CommonFramework/Windows/LabStateV1_Tests.h Source/CommonFramework/Windows/MainWindow.cpp Source/CommonFramework/Windows/MainWindow.h Source/CommonFramework/Windows/WindowTracker.cpp