diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h index 3967ee9e91..906540637b 100644 --- a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_AutoStory_Tests.h @@ -19,6 +19,7 @@ #include "Engine/Pokemon_StoryEngine_Tests.h" #include "Pokemon/Options/Pokemon_StoryRangeOptions_Tests.h" #include "Pokemon_AutoStorySelect_Tests.h" +#include "Pokemon_StoryRun_Tests.h" #include "Pokemon_AutoStoryStats_Tests.h" #include "Pokemon_Interrupts_Tests.h" #include "Pokemon_SceneJudges_Tests.h" @@ -40,6 +41,7 @@ namespace Pokemon{ // Registers every shared AutoStory suite, for the unit test runner. inline void add_tests_AutoStory(UnitTestDatabase& database){ add_tests_AutoStorySelect(database); + add_tests_StoryRun(database); add_tests_AutoStoryStats(database); add_tests_StoryLog(database); add_tests_StoryRangeOptions(database); diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp new file mode 100644 index 0000000000..7e7ff7c736 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp @@ -0,0 +1,130 @@ +/* AutoStory Story Run + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "Pokemon_StoryRun.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +namespace{ + +void log_line(const std::string& line, StoryGameHooks& game){ + if (game.log){ + game.log(line); + } +} + +std::string story_stop_message(const SegmentReport& report){ + if (report.completed){ + return ""; + } + return std::format( + "AutoStory stopped at {} {}: {}", + report.failed_checkpoint, report.failed_event, to_string(report.failure) + ); +} + +std::string story_verify_summary(std::string_view checkpoint, const VerifyPolicy& policy, const VerifyReport& report){ + return std::format( + "AutoStory verify: {} {}/{} passed, {} needed.", checkpoint, report.passes, policy.runs, policy.passes_needed + ); +} + +Outcome load_story_save(std::string_view reason, StoryGameHooks& game, RunState& state){ + log_line(std::format("[Story] {}: loading the save", reason), game); + Outcome outcome = game.load_save(state); + if (outcome.succeeded() && game.check_save_place){ + const std::string error = game.check_save_place(); + if (!error.empty()){ + outcome = outcome_failed("wrong_save", error); + } + } + if (outcome.succeeded() && game.after_load){ + outcome = game.after_load(state); + } + if (!outcome.succeeded()){ + log_line(std::format("[Story] {}", to_string(outcome)), game); + } + return outcome; +} + +} // namespace + +Outcome prepare_story_start(std::string_view checkpoint, StoryStart start, StoryGameHooks& game, RunState& state){ + switch (start){ + case StoryStart::NEW_GAME: + log_line(std::format("[Story] {}: starts a new game, no save to load", checkpoint), game); + return outcome_ok(); + case StoryStart::LIVE: + log_line(std::format("[Story] {}: starts from the game as it is, no save to load", checkpoint), game); + return outcome_ok(); + case StoryStart::FROM_SAVE: + break; + } + Outcome outcome = load_story_save(checkpoint, game, state); + if (outcome.succeeded()){ + state.flags.insert("save_loaded"); + } + return outcome; +} + +SegmentHooks story_segment_hooks(StoryGameHooks& game){ + SegmentHooks hooks; + hooks.reload = [&game](RunState& state){ + return load_story_save("retry", game, state); + }; + hooks.save = [&game](RunState& state){ + if (!game.save){ + return outcome_failed("no_save_hook", "this game's rows save at their start"); + } + return game.save(state); + }; + hooks.log = [&game](const std::string& line){ + log_line(line, game); + }; + hooks.status = [&game](const std::string& line){ + if (game.status){ + game.status(line); + } + }; + return hooks; +} + +void log_story_failure(StoryGameHooks& game){ + log_line(std::string(STORY_LEFT_WHERE_FAILED), game); +} + +std::string finish_story_run(const SegmentReport& report, std::string_view last, AutoStoryStats& stats, StoryGameHooks& game){ + record_story_counts(report.story_counts(), stats); + if (!report.completed){ + log_story_failure(game); + throw OperationFailedException(ErrorReportMode::NO_ERROR_REPORT, story_stop_message(report)); + } + std::string done = std::format("AutoStory: done through {}.", last); + log_line(done, game); + return done; +} + +std::string finish_story_verify( + std::string_view checkpoint, const VerifyPolicy& policy, const VerifyReport& report, StoryGameHooks& game +){ + std::string summary = story_verify_summary(checkpoint, policy, report); + if (!report.verified){ + log_story_failure(game); + throw OperationFailedException(ErrorReportMode::NO_ERROR_REPORT, summary); + } + log_line(summary, game); + return summary; +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h new file mode 100644 index 0000000000..cfbeca7696 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun.h @@ -0,0 +1,92 @@ +/* AutoStory Story Run + * + * From: https://github.com/PokemonAutomation/ + * + * The start and finish of a story run: get the + * game to the start checkpoint, lend the segment runner its reload, and + * finish a run or a verify run with the same log lines, stats and errors. + * A game lends only what really differs: how it loads its save (BDSP + * resets from HOME, FRLG soft-resets) and how it checks where the save is. + * + * Two rules hold for every game: + * - A run that starts at a checkpoint with a save loads that save first, + * so it never walks from wherever the game was left. + * - A failure leaves the game where it failed. Nothing here closes the + * game; the user (or the next run from the save) resumes from there. + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryRun_H +#define PokemonAutomation_Pokemon_StoryRun_H + +#include +#include +#include "Common/Cpp/MoveOnlyFunction.h" +#include "Pokemon_AutoStoryStats.h" +#include "Pokemon_StoryCheckpointTypes.h" +#include "Pokemon_StoryOutcome.h" +#include "Pokemon_StorySegments.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// How the game reaches the start checkpoint. +enum class StoryStart{ + // A new game from the title screen: there is no save. + NEW_GAME, + // The game as another program left it: nothing is loaded. + LIVE, + // The checkpoint's save, loaded first. + FROM_SAVE, +}; + +// What a game lends the story run. +struct StoryGameHooks{ + // Loads the last save: the game reset (from HOME or soft) and back in + // the overworld. A failed Outcome says why. + Act load_save; + // Optional: after a load, "" when the save is where the checkpoint + // about to run starts, else why not. + MoveOnlyFunction check_save_place; + // Optional: after a load and its place check, rereads what the save + // holds (FRLG: the bag's supplies). + Act after_load; + // Optional: saves the game (rows that save at their end). + Act save; + EventLogger log; + // Optional: the step under way, for the video overlay. + EventLogger status; +}; + +// The line logged after any failure. +inline constexpr std::string_view STORY_LEFT_WHERE_FAILED = "AutoStory failed: the game stays where it failed."; + +// Gets the game to where checkpoint `checkpoint` starts, as `start` says. +// FROM_SAVE always loads the save (logging "[Story] 00.04b: loading the +// save"), checks its place and rereads it, and sets the "save_loaded" flag. +Outcome prepare_story_start(std::string_view checkpoint, StoryStart start, StoryGameHooks& game, RunState& state); + +// The runner's hooks: reload is load_story_save(); save, log and status +// are the game's. `game` must outlive them. +SegmentHooks story_segment_hooks(StoryGameHooks& game); + +// Ends a run: its counts into `stats`, then the failure line and an +// OperationFailedException if it stopped short, else "AutoStory: done +// through ." Returns that line, for the finish notification. +std::string finish_story_run(const SegmentReport& report, std::string_view last, AutoStoryStats& stats, StoryGameHooks& game); + +// Ends a verify run: the summary, and the failure line and an +// OperationFailedException unless verified. Returns the summary. +std::string finish_story_verify( + std::string_view checkpoint, const VerifyPolicy& policy, const VerifyReport& report, StoryGameHooks& game +); + +// The failure line, for a game whose run threw before the story run saw it. +void log_story_failure(StoryGameHooks& game); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp new file mode 100644 index 0000000000..dd5ecc7a33 --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp @@ -0,0 +1,236 @@ +/* AutoStory Story Run Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "CommonFramework/Exceptions/OperationFailedException.h" +#include "Pokemon_StoryRun.h" +#include "Pokemon_StoryRun_Tests.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + +namespace{ + +// A game that records what the story run asked of it. +struct FakeGame{ + std::string place_error; + size_t loads = 0; + size_t rereads = 0; + size_t saves = 0; + std::vector lines; + + StoryGameHooks hooks(){ + StoryGameHooks game; + game.load_save = [this](RunState&){ + loads++; + return outcome_ok(); + }; + game.check_save_place = [this]{ + return place_error; + }; + game.after_load = [this](RunState&){ + rereads++; + return outcome_ok(); + }; + game.save = [this](RunState&){ + saves++; + return outcome_ok(); + }; + game.log = [this](const std::string& line){ + lines.push_back(line); + }; + return game; + } + bool logged(std::string_view line) const{ + for (const std::string& logged_line : lines){ + if (logged_line == line){ + return true; + } + } + return false; + } +}; + +// A start as the program asks for it, and what the game must have done. +struct StartCase{ + std::string name; + StoryStart start; + std::string place_error; + bool succeeds; + size_t loads; + size_t rereads; + bool save_loaded; +}; + +class Test_StoryStart : public UnitTest{ +public: + Test_StoryStart(StartCase test_case) + : UnitTest(std::format("Pokemon::StoryRun - start: {}", test_case.name)) + , m_case(std::move(test_case)) + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + FakeGame fake; + fake.place_error = m_case.place_error; + StoryGameHooks game = fake.hooks(); + RunState state; + const Outcome outcome = prepare_story_start("00.04b", m_case.start, game, state); + const bool save_loaded = state.flags.contains("save_loaded"); + if (outcome.succeeded() != m_case.succeeds || fake.loads != m_case.loads + || fake.rereads != m_case.rereads || save_loaded != m_case.save_loaded + ){ + return std::format( + "Expected ok={} loads={} rereads={} save_loaded={}, got {} {} {} {} ({})", + m_case.succeeds, m_case.loads, m_case.rereads, m_case.save_loaded, + outcome.succeeded(), fake.loads, fake.rereads, save_loaded, to_string(outcome) + ); + } + return true; + } + +private: + const StartCase m_case; +}; + +const StartCase START_CASES[] = { + // Console B, 2026-11-11: a BDSP run started at 00.04b with the game + // left at 00.04d walked from 00.04d's position. + {"a checkpoint with a save loads it first", StoryStart::FROM_SAVE, "", true, 1, 1, true}, + {"a save in the wrong place fails before rereading it", StoryStart::FROM_SAVE, "The save is in Pewter City.", false, 1, 0, false}, + {"a new game loads nothing", StoryStart::NEW_GAME, "", true, 0, 0, false}, + {"a live start loads nothing", StoryStart::LIVE, "", true, 0, 0, false}, +}; + + +// A failed attempt's reload loads the save through the game. +class Test_StoryReload : public UnitTest{ +public: + Test_StoryReload() + : UnitTest("Pokemon::StoryRun - a retry reloads the save") + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + FakeGame fake; + StoryGameHooks game = fake.hooks(); + SegmentHooks hooks = story_segment_hooks(game); + RunState state; + const Outcome outcome = hooks.reload(state); + if (!outcome.succeeded() || fake.loads != 1 || fake.rereads != 1 || !fake.logged("[Story] retry: loading the save")){ + return std::format("Expected one load and reread, got {} and {} ({})", fake.loads, fake.rereads, to_string(outcome)); + } + return true; + } +}; + + +// A run that stopped short throws, logs the failure line and touches +// nothing in the game: no reload, no save, no reset to HOME. +class Test_StoryFailureLeavesGame : public UnitTest{ +public: + Test_StoryFailureLeavesGame() + : UnitTest("Pokemon::StoryRun - a failed run leaves the game where it failed") + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + FakeGame fake; + StoryGameHooks game = fake.hooks(); + SegmentReport report; + report.completed = false; + report.failed_checkpoint = "00.04b"; + report.failed_event = "talk_mom"; + report.failure = outcome_failed("expect_failed", "dialogue opened"); + AutoStoryStats stats; + std::string message; + try{ + finish_story_run(report, "00.05", stats, game); + return "Expected an OperationFailedException"; + }catch (OperationFailedException& e){ + message = e.message(); + } + if (message != "AutoStory stopped at 00.04b talk_mom: expect_failed: dialogue opened"){ + return std::format("Unexpected message: {}", message); + } + if (!fake.logged(STORY_LEFT_WHERE_FAILED)){ + return "Expected the failure line"; + } + if (fake.loads != 0 || fake.saves != 0){ + return std::format("Expected the game untouched, got {} loads and {} saves", fake.loads, fake.saves); + } + return true; + } +}; + + +// A completed run logs and returns the line the finish notification sends. +class Test_StoryFinished : public UnitTest{ +public: + Test_StoryFinished() + : UnitTest("Pokemon::StoryRun - a completed run is done through its last checkpoint") + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + FakeGame fake; + StoryGameHooks game = fake.hooks(); + SegmentReport report; + report.completed = true; + AutoStoryStats stats; + const std::string done = finish_story_run(report, "00.05", stats, game); + if (done != "AutoStory: done through 00.05." || !fake.logged(done)){ + return std::format("Unexpected finish line: {}", done); + } + return true; + } +}; + + +// A verify run short of its passes throws with the summary. +class Test_StoryVerifyFailed : public UnitTest{ +public: + Test_StoryVerifyFailed() + : UnitTest("Pokemon::StoryRun - an unverified checkpoint fails with its summary") + {} + + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + FakeGame fake; + StoryGameHooks game = fake.hooks(); + VerifyPolicy policy; + VerifyReport report; + report.passes = 1; + report.verified = false; + std::string message; + try{ + finish_story_verify("00.15b", policy, report, game); + return "Expected an OperationFailedException"; + }catch (OperationFailedException& e){ + message = e.message(); + } + if (message != "AutoStory verify: 00.15b 1/3 passed, 2 needed." || !fake.logged(STORY_LEFT_WHERE_FAILED)){ + return std::format("Unexpected message: {}", message); + } + return true; + } +}; + +} // namespace + + +void add_tests_StoryRun(UnitTestDatabase& database){ + for (const StartCase& test_case : START_CASES){ + database.add(test_case); + } + database.add(); + database.add(); + database.add(); + database.add(); +} + + + +} // namespace Pokemon +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.h b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.h new file mode 100644 index 0000000000..d1ac79aa1a --- /dev/null +++ b/SerialPrograms/Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.h @@ -0,0 +1,23 @@ +/* AutoStory Story Run Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_Pokemon_StoryRun_Tests_H +#define PokemonAutomation_Pokemon_StoryRun_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ +namespace Pokemon{ + + +// Registers unit tests for the AutoStory story run's start, reload and finish. +void add_tests_StoryRun(UnitTestDatabase& database); + + + +} // namespace Pokemon +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/cmake/SourceFiles.cmake b/SerialPrograms/cmake/SourceFiles.cmake index a0fdfd3863..9c4fe82434 100644 --- a/SerialPrograms/cmake/SourceFiles.cmake +++ b/SerialPrograms/cmake/SourceFiles.cmake @@ -1546,6 +1546,10 @@ file(GLOB LIBRARY_SOURCES Source/Pokemon/AutoStory/Pokemon_AutoStorySelect.h Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.cpp Source/Pokemon/AutoStory/Pokemon_AutoStorySelect_Tests.h + Source/Pokemon/AutoStory/Pokemon_StoryRun.cpp + Source/Pokemon/AutoStory/Pokemon_StoryRun.h + Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.cpp + Source/Pokemon/AutoStory/Pokemon_StoryRun_Tests.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.cpp Source/Pokemon/AutoStory/Pokemon_AutoStoryStats.h Source/Pokemon/AutoStory/Pokemon_AutoStoryStats_Tests.cpp