From b913c8939297710742f0f47e1219f6a1556157ee Mon Sep 17 00:00:00 2001
From: Pepe <pepe@ross-robotics.co.uk>
Date: Thu, 2 Apr 2026 22:52:12 +0100
Subject: [PATCH 1/3] Enhances TestNode with script-based return status and
 conditional post-scripts

Introduces `return_status_script` to allow dynamic computation of the TestNode's completion status based on blackboard variables at runtime. This provides greater flexibility for mocking different scenarios in tests.

Refines post-execution logic by replacing a single `post_script` with distinct `success_script` and `failure_script` that execute based on the TestNode's final status. The `return_status_script` takes precedence over a statically defined `return_status`.

Adds comprehensive validation to prevent the TestNode from returning an `IDLE` status and to ensure a valid completion status mechanism is always configured.
---
 examples/CMakeLists.txt                       |   1 +
 examples/t15_nodes_mocking.cpp                |  46 +++--
 examples/t15_nodes_mocking_strict_failure.cpp | 145 +++++++++++++++
 include/behaviortree_cpp/actions/test_node.h  |  31 +++-
 src/actions/test_node.cpp                     | 107 +++++++++++-
 src/bt_factory.cpp                            |  18 +-
 tests/gtest_substitution.cpp                  | 165 +++++++++++++++++-
 7 files changed, 484 insertions(+), 29 deletions(-)
 create mode 100644 examples/t15_nodes_mocking_strict_failure.cpp

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 9a94c95e8..7ccb5f05d 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -35,6 +35,7 @@ CompileExample("t12_default_ports")
 CompileExample("t13_access_by_ref")
 CompileExample("t14_subtree_model")
 CompileExample("t15_nodes_mocking")
+CompileExample("t15_nodes_mocking_strict_failure")
 CompileExample("t16_global_blackboard")
 CompileExample("t17_blackboard_backup")
 CompileExample("t18_waypoints")
diff --git a/examples/t15_nodes_mocking.cpp b/examples/t15_nodes_mocking.cpp
index 805a46b95..78d276872 100644
--- a/examples/t15_nodes_mocking.cpp
+++ b/examples/t15_nodes_mocking.cpp
@@ -14,8 +14,14 @@ const char* xml_text = R"(
 
       <SubTree ID="MySub" name="mysub"/>
 
-      <Script name="set_message" code="msg:= 'the original message' "/>
-      <SaySomething message="{msg}"/>
+      <Script name="set_mock_flag" code="mock_should_fail:= false"/>
+      <Fallback name="report_mock_message">
+        <Sequence>
+          <Script name="set_message" code="msg:= 'the original message' "/>
+          <SaySomething message="{msg}"/>
+        </Sequence>
+        <SaySomething message="{msg}"/>
+      </Fallback>
 
       <Sequence name="counting">
         <SaySomething message="1"/>
@@ -39,7 +45,14 @@ const char* xml_text = R"(
 
 /**
  * @brief In this example we will see how we can substitute some nodes
- * in the Tree above with
+ * in the Tree above with mocks.
+ *
+ * This variant is optimized for observability: even when the substituted
+ * TestNode resolves to FAILURE, a Fallback logs the final message from inside
+ * the tree.
+ *
+ * See t15_nodes_mocking_strict_failure.cpp for the companion example that
+ * preserves strict failure propagation instead.
  * @param argc
  * @param argv
  * @return
@@ -90,12 +103,16 @@ int main(int /*argc*/, char** /*argv*/)
 
   // This is the configuration passed to the TestNode
   BT::TestNodeConfig test_config;
-  // we want this to return always SUCCESS
-  test_config.return_status = BT::NodeStatus::SUCCESS;
+  // the returned status can also be computed from a script.
+    // Change mock_should_fail to true in the XML above to see the failure path.
+  test_config.return_status.reset();
+  test_config.return_status_script =
+      "(mock_should_fail == true) ? FAILURE : SUCCESS";
   // Convert the node in asynchronous and wait 2000 ms
   test_config.async_delay = std::chrono::milliseconds(2000);
-  // Execute this postcondition, once completed
-  test_config.post_script = "msg := 'message SUBSTITUTED' ";
+  // Execute a different script depending on the resolved return status.
+  test_config.success_script = "msg := 'message SUBSTITUTED' ";
+  test_config.failure_script = "msg := 'message FAILURE branch' ";
 
   // this will be synchronous (async_delay is 0)
   BT::TestNodeConfig counting_config;
@@ -130,8 +147,9 @@ int main(int /*argc*/, char** /*argv*/)
       "TestNodeConfigs": {
         "NewMessage": {
           "async_delay": 2000,
-          "return_status": "SUCCESS",
-          "post_script": "msg ='message SUBSTITUTED'"
+          "return_status_script": "(mock_should_fail == true) ? FAILURE : SUCCESS",
+          "success_script": "msg ='message SUBSTITUTED'",
+          "failure_script": "msg ='message FAILURE branch'"
         },
         "NoCounting": {
           "return_status": "SUCCESS"
@@ -169,12 +187,16 @@ mysub
 mysub/Sequence::4
 mysub/action_subA
 mysub/action_subB
+set_mock_flag
+report_mock_message
+Sequence::9
 set_message
-SaySomething::8
-counting
-SaySomething::10
 SaySomething::11
 SaySomething::12
+counting
+SaySomething::14
+SaySomething::15
+SaySomething::16
 
 ------ Output (original) ------
 Robot says: hello world
diff --git a/examples/t15_nodes_mocking_strict_failure.cpp b/examples/t15_nodes_mocking_strict_failure.cpp
new file mode 100644
index 000000000..00d22c7bf
--- /dev/null
+++ b/examples/t15_nodes_mocking_strict_failure.cpp
@@ -0,0 +1,145 @@
+#include "dummy_nodes.h"
+
+#include "behaviortree_cpp/bt_factory.h"
+
+// clang-format off
+namespace
+{
+const char* xml_text = R"(
+<root BTCPP_format="4">
+
+  <BehaviorTree ID="MainTree">
+    <Sequence>
+      <SaySomething name="talk" message="hello world"/>
+
+      <SubTree ID="MySub" name="mysub"/>
+
+      <Script name="set_mock_flag" code="mock_should_fail:= false"/>
+      <Script name="set_message" code="msg:= 'the original message' "/>
+      <SaySomething message="{msg}"/>
+
+      <Sequence name="counting">
+        <SaySomething message="1"/>
+        <SaySomething message="2"/>
+        <SaySomething message="3"/>
+      </Sequence>
+    </Sequence>
+  </BehaviorTree>
+
+  <BehaviorTree ID="MySub">
+    <Sequence>
+      <AlwaysSuccess name="action_subA"/>
+      <AlwaysSuccess name="action_subB"/>
+    </Sequence>
+  </BehaviorTree>
+
+</root>
+ )";
+}  // namespace
+// clang-format on
+
+/**
+ * @brief Companion to tutorial 15 that preserves strict failure propagation.
+ *
+ * If the substituted TestNode resolves to FAILURE, the enclosing Sequence stops
+ * immediately. The final blackboard message is still printed by this executable,
+ * but the tree itself does not log the failure branch through a fallback.
+ */
+
+int main(int /*argc*/, char** /*argv*/)
+{
+  using namespace DummyNodes;
+  BT::BehaviorTreeFactory factory;
+  factory.registerNodeType<SaySomething>("SaySomething");
+  factory.registerBehaviorTreeFromText(xml_text);
+
+  {
+    auto tree = factory.createTree("MainTree");
+
+    std::cout << "----- Nodes fullPath() -------\n";
+    tree.applyVisitor(
+        [](BT::TreeNode* node) { std::cout << node->fullPath() << std::endl; });
+
+    std::cout << "\n------ Output (original) ------\n";
+    auto status = tree.tickWhileRunning();
+    std::cout << "Original status: " << BT::toStr(status, false) << std::endl;
+  }
+
+  factory.registerSimpleAction("DummyAction", [](BT::TreeNode& self) {
+    std::cout << "DummyAction substituting node with fullPath(): " << self.fullPath()
+              << std::endl;
+    return BT::NodeStatus::SUCCESS;
+  });
+
+  factory.registerSimpleAction("DummySaySomething", [](BT::TreeNode& self) {
+    auto msg = self.getInput<std::string>("message");
+    std::cout << "DummySaySomething: " << msg.value() << std::endl;
+    return BT::NodeStatus::SUCCESS;
+  });
+
+  BT::TestNodeConfig test_config;
+  test_config.return_status.reset();
+  test_config.return_status_script =
+      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.async_delay = std::chrono::milliseconds(2000);
+  test_config.success_script = "msg := 'message SUBSTITUTED' ";
+  test_config.failure_script = "msg := 'message FAILURE branch' ";
+
+  BT::TestNodeConfig counting_config;
+  counting_config.return_status = BT::NodeStatus::SUCCESS;
+
+  factory.addSubstitutionRule("mysub/action_*", "DummyAction");
+  factory.addSubstitutionRule("talk", "DummySaySomething");
+  factory.addSubstitutionRule("set_message", test_config);
+  factory.addSubstitutionRule("counting", counting_config);
+
+  auto blackboard = BT::Blackboard::create();
+  auto tree = factory.createTree("MainTree", blackboard);
+  std::cout << "\n------ Output (substituted, strict failure) ------\n";
+  auto status = tree.tickWhileRunning();
+  std::cout << "Substituted status: " << BT::toStr(status, false) << std::endl;
+  if(blackboard->getEntry("msg"))
+  {
+    std::cout << "Substituted final msg: " << blackboard->get<std::string>("msg")
+              << std::endl;
+  }
+
+  return 0;
+}
+
+/* Expected output:
+
+----- Nodes fullPath() -------
+Sequence::1
+talk
+mysub
+mysub/Sequence::4
+mysub/action_subA
+mysub/action_subB
+set_mock_flag
+set_message
+SaySomething::9
+counting
+SaySomething::11
+SaySomething::12
+SaySomething::13
+
+------ Output (original) ------
+Robot says: hello world
+Robot says: the original message
+Robot says: 1
+Robot says: 2
+Robot says: 3
+Original status: SUCCESS
+
+------ Output (substituted, strict failure) ------
+DummySaySomething: hello world
+DummyAction substituting node with fullPath(): mysub/action_subA
+DummyAction substituting node with fullPath(): mysub/action_subB
+Substituted status: SUCCESS
+Substituted final msg: message SUBSTITUTED
+
+If you change mock_should_fail to true in the XML above, the substituted status
+becomes FAILURE and the final msg becomes "message FAILURE branch".
+
+*/
diff --git a/include/behaviortree_cpp/actions/test_node.h b/include/behaviortree_cpp/actions/test_node.h
index 17b91a23f..378fac94e 100644
--- a/include/behaviortree_cpp/actions/test_node.h
+++ b/include/behaviortree_cpp/actions/test_node.h
@@ -13,6 +13,10 @@
 
 #pragma once
 
+#include <memory>
+#include <optional>
+#include <string>
+
 #include "behaviortree_cpp/action_node.h"
 #include "behaviortree_cpp/scripting/script_parser.hpp"
 #include "behaviortree_cpp/utils/timer_queue.h"
@@ -22,8 +26,19 @@ namespace BT
 
 struct TestNodeConfig
 {
-  /// status to return when the action is completed.
-  NodeStatus return_status = NodeStatus::SUCCESS;
+  /// Status to return when the action is completed.
+  ///
+  /// If both return_status and return_status_script are specified,
+  /// return_status_script takes precedence.
+  std::optional<NodeStatus> return_status = NodeStatus::SUCCESS;
+
+  /// Optional script to compute the completion status dynamically.
+  ///
+  /// This script is evaluated when the TestNode completes, after any
+  /// async_delay has elapsed, using the current blackboard state.
+  /// The result must resolve to the same set of statuses supported by
+  /// return_status, except IDLE which is always rejected.
+  std::string return_status_script;
 
   /// script to execute when complete_func() returns SUCCESS
   std::string success_script;
@@ -38,7 +53,8 @@ struct TestNodeConfig
   std::chrono::milliseconds async_delay = std::chrono::milliseconds(0);
 
   /// Function invoked when the action is completed.
-  /// If not specified, the node will return [return_status]
+  /// If not specified, the node will use return_status_script when present,
+  /// otherwise it will return [return_status].
   std::function<NodeStatus(void)> complete_func;
 };
 
@@ -46,6 +62,7 @@ struct TestNodeConfig
  * @brief The TestNode is a Node that can be configure to:
  *
  * 1. Return a specific status (SUCCESS / FAILURE)
+ * 1.b Compute the returned status from a script evaluated at completion time
  * 2. Execute a post condition script (unless halted)
  * 3. Either complete immediately (synchronous action), or after a
  *    given period of time (asynchronous action)
@@ -79,15 +96,17 @@ class TestNode : public BT::StatefulActionNode
   }
 
 protected:
-  virtual NodeStatus onStart() override;
+  NodeStatus onStart() override;
 
-  virtual NodeStatus onRunning() override;
+  NodeStatus onRunning() override;
 
-  virtual void onHalted() override;
+  void onHalted() override;
 
   NodeStatus onCompleted();
 
   std::shared_ptr<TestNodeConfig> _config;
+  EnumsTablePtr _script_enums;
+  ScriptFunction _return_status_executor;
   ScriptFunction _success_executor;
   ScriptFunction _failure_executor;
   ScriptFunction _post_executor;
diff --git a/src/actions/test_node.cpp b/src/actions/test_node.cpp
index f2471c085..ac5fd11b7 100644
--- a/src/actions/test_node.cpp
+++ b/src/actions/test_node.cpp
@@ -3,6 +3,74 @@
 namespace BT
 {
 
+namespace
+{
+
+bool isAllowedTestNodeStatus(NodeStatus status)
+{
+  switch(status)
+  {
+    case NodeStatus::RUNNING:
+    case NodeStatus::SUCCESS:
+    case NodeStatus::FAILURE:
+    case NodeStatus::SKIPPED:
+      return true;
+
+    case NodeStatus::IDLE:
+      return false;
+  }
+  return false;
+}
+
+void validateTestNodeStatus(NodeStatus status, StringView source)
+{
+  if(!isAllowedTestNodeStatus(status))
+  {
+    throw RuntimeError("TestNode ", std::string(source),
+                       " resolved to invalid status IDLE");
+  }
+}
+
+EnumsTablePtr createTestNodeEnums(const EnumsTablePtr& base_enums)
+{
+  auto enums = base_enums ? std::make_shared<EnumsTable>(*base_enums)
+                          : std::make_shared<EnumsTable>();
+
+  (*enums)["IDLE"] = static_cast<int>(NodeStatus::IDLE);
+  (*enums)["RUNNING"] = static_cast<int>(NodeStatus::RUNNING);
+  (*enums)["SUCCESS"] = static_cast<int>(NodeStatus::SUCCESS);
+  (*enums)["FAILURE"] = static_cast<int>(NodeStatus::FAILURE);
+  (*enums)["SKIPPED"] = static_cast<int>(NodeStatus::SKIPPED);
+  return enums;
+}
+
+NodeStatus convertScriptResultToStatus(const Any& result)
+{
+  if(result.empty())
+  {
+    throw RuntimeError("return_status_script returned an empty value");
+  }
+
+  if(result.isString())
+  {
+    auto status = convertFromString<NodeStatus>(result.cast<std::string>());
+    validateTestNodeStatus(status, "return_status_script");
+    return status;
+  }
+
+  if(auto status = result.tryCast<int>())
+  {
+    auto resolved = static_cast<NodeStatus>(status.value());
+    validateTestNodeStatus(resolved, "return_status_script");
+    return resolved;
+  }
+
+  throw RuntimeError("return_status_script must evaluate to a NodeStatus-compatible "
+                     "value");
+}
+
+}  // namespace
+
 TestNode::TestNode(const std::string& name, const NodeConfig& config,
                    TestNodeConfig test_config)
   : TestNode(name, config, std::make_shared<TestNodeConfig>(std::move(test_config)))
@@ -14,11 +82,20 @@ TestNode::TestNode(const std::string& name, const NodeConfig& config,
 {
   setRegistrationID("TestNode");
 
-  if(_config->return_status == NodeStatus::IDLE)
+  if(_config->return_status)
+  {
+    validateTestNodeStatus(_config->return_status.value(), "return_status");
+  }
+
+  if(!_config->complete_func && !_config->return_status &&
+     _config->return_status_script.empty())
   {
-    throw RuntimeError("TestNode can not return IDLE");
+    throw RuntimeError(
+        "TestNode requires one of complete_func, return_status, or return_status_script");
   }
 
+  _script_enums = createTestNodeEnums(config.enums);
+
   auto prepareScript = [](const std::string& script, auto& executor) {
     if(!script.empty())
     {
@@ -30,6 +107,7 @@ TestNode::TestNode(const std::string& name, const NodeConfig& config,
       executor = result.value();
     }
   };
+  prepareScript(_config->return_status_script, _return_status_executor);
   prepareScript(_config->success_script, _success_executor);
   prepareScript(_config->failure_script, _failure_executor);
   prepareScript(_config->post_script, _post_executor);
@@ -74,10 +152,29 @@ void TestNode::onHalted()
 
 NodeStatus TestNode::onCompleted()
 {
-  Ast::Environment env = { config().blackboard, config().enums };
+  Ast::Environment env = { config().blackboard, _script_enums };
+
+  NodeStatus status = NodeStatus::IDLE;
+
+  if(_config->complete_func)
+  {
+    status = _config->complete_func();
+  }
+  else if(_return_status_executor)
+  {
+    status = convertScriptResultToStatus(_return_status_executor(env));
+  }
+  else if(_config->return_status)
+  {
+    status = _config->return_status.value();
+  }
+  else
+  {
+    throw RuntimeError(
+        "TestNode requires one of complete_func, return_status, or return_status_script");
+  }
 
-  auto status =
-      (_config->complete_func) ? _config->complete_func() : _config->return_status;
+  validateTestNodeStatus(status, "completion");
 
   if(status == NodeStatus::SUCCESS && _success_executor)
   {
diff --git a/src/bt_factory.cpp b/src/bt_factory.cpp
index 42cf43307..c4e9c8e03 100644
--- a/src/bt_factory.cpp
+++ b/src/bt_factory.cpp
@@ -531,9 +531,17 @@ void BehaviorTreeFactory::loadSubstitutionRuleFromJSON(const std::string& json_t
     for(auto const& [name, test_config] : test_configs.items())
     {
       auto& config = configs[name];
+      config.return_status.reset();
 
-      auto return_status = test_config.at("return_status").get<std::string>();
-      config.return_status = convertFromString<NodeStatus>(return_status);
+      if(test_config.contains("return_status"))
+      {
+        auto return_status = test_config.at("return_status").get<std::string>();
+        config.return_status = convertFromString<NodeStatus>(return_status);
+      }
+      if(test_config.contains("return_status_script"))
+      {
+        config.return_status_script = test_config["return_status_script"].get<std::string>();
+      }
       if(test_config.contains("async_delay"))
       {
         config.async_delay =
@@ -551,6 +559,12 @@ void BehaviorTreeFactory::loadSubstitutionRuleFromJSON(const std::string& json_t
       {
         config.failure_script = test_config["failure_script"].get<std::string>();
       }
+
+      if(!config.return_status && config.return_status_script.empty())
+      {
+        throw RuntimeError("TestNodeConfig [", name,
+                           "] must contain return_status or return_status_script");
+      }
     }
   }
 
diff --git a/tests/gtest_substitution.cpp b/tests/gtest_substitution.cpp
index 172d9ce64..23ef0c074 100644
--- a/tests/gtest_substitution.cpp
+++ b/tests/gtest_substitution.cpp
@@ -19,13 +19,18 @@ const char* json_text = R"(
     },
     "TestB": {
       "return_status": "FAILURE"
+    },
+    "TestScript": {
+      "return_status_script": "(mock_should_fail == true) ? FAILURE : SUCCESS",
+      "failure_script": "branch := 'failure'"
     }
   },
 
   "SubstitutionRules": {
     "actionA": "TestA",
     "actionB": "TestB",
-    "actionC": "NotAConfig"
+    "actionC": "NotAConfig",
+    "actionD": "TestScript"
   }
 }
  )";
@@ -40,24 +45,176 @@ TEST(Substitution, Parser)
 
   const auto& rules = factory.substitutionRules();
 
-  ASSERT_EQ(rules.size(), 3);
+  ASSERT_EQ(rules.size(), 4);
   ASSERT_EQ(rules.count("actionA"), 1);
   ASSERT_EQ(rules.count("actionB"), 1);
   ASSERT_EQ(rules.count("actionC"), 1);
+  ASSERT_EQ(rules.count("actionD"), 1);
 
   auto configA = std::get_if<TestNodeConfig>(&rules.at("actionA"));
-  ASSERT_EQ(configA->return_status, NodeStatus::SUCCESS);
+  ASSERT_TRUE(configA->return_status.has_value());
+  ASSERT_EQ(configA->return_status.value(), NodeStatus::SUCCESS);
   ASSERT_EQ(configA->async_delay, std::chrono::milliseconds(2000));
   ASSERT_EQ(configA->post_script, "msg ='message SUBSTITUED'");
 
   auto configB = std::get_if<TestNodeConfig>(&rules.at("actionB"));
-  ASSERT_EQ(configB->return_status, NodeStatus::FAILURE);
+  ASSERT_TRUE(configB->return_status.has_value());
+  ASSERT_EQ(configB->return_status.value(), NodeStatus::FAILURE);
   ASSERT_EQ(configB->async_delay, std::chrono::milliseconds(0));
   ASSERT_TRUE(configB->post_script.empty());
 
+  auto configScript = std::get_if<TestNodeConfig>(&rules.at("actionD"));
+  ASSERT_FALSE(configScript->return_status.has_value());
+  ASSERT_EQ(configScript->return_status_script,
+            "(mock_should_fail == true) ? FAILURE : SUCCESS");
+  ASSERT_EQ(configScript->failure_script, "branch := 'failure'");
+
   ASSERT_EQ(*std::get_if<std::string>(&rules.at("actionC")), "NotAConfig");
 }
 
+TEST(Substitution, ParserRejectsMissingReturnStatusAndScript)
+{
+  static const char* invalid_json = R"(
+  {
+    "TestNodeConfigs": {
+      "BrokenConfig": {
+        "post_script": "branch := 'unused'"
+      }
+    },
+    "SubstitutionRules": {
+      "actionA": "BrokenConfig"
+    }
+  }
+  )";
+
+  BehaviorTreeFactory factory;
+  ASSERT_THROW(factory.loadSubstitutionRuleFromJSON(invalid_json), RuntimeError);
+}
+
+TEST(Substitution, ScriptedReturnStatusFromJson)
+{
+  static const char* xml_text = R"(
+  <root BTCPP_format="4">
+    <BehaviorTree ID="MainTree">
+      <Sequence>
+        <Script code="mock_should_fail := true"/>
+        <AlwaysSuccess name="action_A"/>
+      </Sequence>
+    </BehaviorTree>
+  </root>
+  )";
+
+  static const char* json_rules = R"(
+  {
+    "TestNodeConfigs": {
+      "ConditionalMock": {
+        "return_status_script": "(mock_should_fail == true) ? FAILURE : SUCCESS",
+        "success_script": "branch := 'success'",
+        "failure_script": "branch := 'failure'"
+      }
+    },
+    "SubstitutionRules": {
+      "action_A": "ConditionalMock"
+    }
+  }
+  )";
+
+  BehaviorTreeFactory factory;
+  factory.loadSubstitutionRuleFromJSON(json_rules);
+  factory.registerBehaviorTreeFromText(xml_text);
+
+  auto blackboard = Blackboard::create();
+  auto tree = factory.createTree("MainTree", blackboard);
+
+  ASSERT_EQ(tree.tickWhileRunning(), NodeStatus::FAILURE);
+  ASSERT_EQ(blackboard->get<std::string>("branch"), "failure");
+}
+
+TEST(Substitution, ScriptedReturnStatusOverridesFixedStatus)
+{
+  static const char* xml_text = R"(
+  <root BTCPP_format="4">
+    <BehaviorTree ID="MainTree">
+      <Sequence>
+        <Script code="mock_should_fail := true"/>
+        <AlwaysSuccess name="action_A"/>
+      </Sequence>
+    </BehaviorTree>
+  </root>
+  )";
+
+  BehaviorTreeFactory factory;
+  factory.registerBehaviorTreeFromText(xml_text);
+
+  TestNodeConfig test_config;
+  test_config.return_status = NodeStatus::SUCCESS;
+  test_config.return_status_script =
+      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.failure_script = "branch := 'failure'";
+  factory.addSubstitutionRule("action_A", test_config);
+
+  auto blackboard = Blackboard::create();
+  auto tree = factory.createTree("MainTree", blackboard);
+
+  ASSERT_EQ(tree.tickWhileRunning(), NodeStatus::FAILURE);
+  ASSERT_EQ(blackboard->get<std::string>("branch"), "failure");
+}
+
+TEST(Substitution, ScriptedReturnStatusAsyncSubstitution)
+{
+  static const char* xml_text = R"(
+  <root BTCPP_format="4">
+    <BehaviorTree ID="MainTree">
+      <Sequence>
+        <Script code="mock_should_fail := false"/>
+        <AlwaysSuccess name="action_A"/>
+      </Sequence>
+    </BehaviorTree>
+  </root>
+  )";
+
+  BehaviorTreeFactory factory;
+  factory.registerBehaviorTreeFromText(xml_text);
+
+  TestNodeConfig test_config;
+  test_config.return_status.reset();
+  test_config.return_status_script =
+      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.async_delay = std::chrono::milliseconds(50);
+  factory.addSubstitutionRule("action_A", test_config);
+
+  auto tree = factory.createTree("MainTree");
+  auto future =
+      std::async(std::launch::async, [&tree]() { return tree.tickWhileRunning(); });
+
+  auto status = future.wait_for(std::chrono::seconds(5));
+  ASSERT_NE(status, std::future_status::timeout)
+      << "Tree hung! tickWhileRunning did not complete within 5 seconds";
+  ASSERT_EQ(future.get(), NodeStatus::SUCCESS);
+}
+
+TEST(Substitution, ScriptedReturnStatusRejectsIdle)
+{
+  static const char* xml_text = R"(
+  <root BTCPP_format="4">
+    <BehaviorTree ID="MainTree">
+      <AlwaysSuccess name="action_A"/>
+    </BehaviorTree>
+  </root>
+  )";
+
+  BehaviorTreeFactory factory;
+  factory.registerBehaviorTreeFromText(xml_text);
+
+  TestNodeConfig test_config;
+  test_config.return_status.reset();
+  test_config.return_status_script = "IDLE";
+  factory.addSubstitutionRule("action_A", test_config);
+
+  auto tree = factory.createTree("MainTree");
+  ASSERT_THROW(tree.tickWhileRunning(), RuntimeError);
+}
+
 // Regression test for issue #934: segfault when substituting a SubTree node
 TEST(Substitution, SubTreeNodeSubstitution)
 {

From 78be5879c6f5e5357990f2bcdcd38de24bee2ef6 Mon Sep 17 00:00:00 2001
From: Pepe <pepe@ross-robotics.co.uk>
Date: Thu, 2 Apr 2026 23:03:47 +0100
Subject: [PATCH 2/3] Applies consistent code formatting

Adjusts line wrapping and whitespace across examples, headers, source files, and tests
to enhance readability and maintain a unified code style.
---
 examples/t15_nodes_mocking.cpp                |  5 ++---
 examples/t15_nodes_mocking_strict_failure.cpp |  3 +--
 include/behaviortree_cpp/actions/test_node.h  |  8 ++++----
 src/actions/test_node.cpp                     | 12 ++++++------
 src/bt_factory.cpp                            |  3 ++-
 tests/gtest_substitution.cpp                  | 14 ++++++--------
 6 files changed, 21 insertions(+), 24 deletions(-)

diff --git a/examples/t15_nodes_mocking.cpp b/examples/t15_nodes_mocking.cpp
index 78d276872..2921ed177 100644
--- a/examples/t15_nodes_mocking.cpp
+++ b/examples/t15_nodes_mocking.cpp
@@ -104,10 +104,9 @@ int main(int /*argc*/, char** /*argv*/)
   // This is the configuration passed to the TestNode
   BT::TestNodeConfig test_config;
   // the returned status can also be computed from a script.
-    // Change mock_should_fail to true in the XML above to see the failure path.
+  // Change mock_should_fail to true in the XML above to see the failure path.
   test_config.return_status.reset();
-  test_config.return_status_script =
-      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.return_status_script = "(mock_should_fail == true) ? FAILURE : SUCCESS";
   // Convert the node in asynchronous and wait 2000 ms
   test_config.async_delay = std::chrono::milliseconds(2000);
   // Execute a different script depending on the resolved return status.
diff --git a/examples/t15_nodes_mocking_strict_failure.cpp b/examples/t15_nodes_mocking_strict_failure.cpp
index 00d22c7bf..560c4a972 100644
--- a/examples/t15_nodes_mocking_strict_failure.cpp
+++ b/examples/t15_nodes_mocking_strict_failure.cpp
@@ -79,8 +79,7 @@ int main(int /*argc*/, char** /*argv*/)
 
   BT::TestNodeConfig test_config;
   test_config.return_status.reset();
-  test_config.return_status_script =
-      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.return_status_script = "(mock_should_fail == true) ? FAILURE : SUCCESS";
   test_config.async_delay = std::chrono::milliseconds(2000);
   test_config.success_script = "msg := 'message SUBSTITUTED' ";
   test_config.failure_script = "msg := 'message FAILURE branch' ";
diff --git a/include/behaviortree_cpp/actions/test_node.h b/include/behaviortree_cpp/actions/test_node.h
index 378fac94e..dd72491ed 100644
--- a/include/behaviortree_cpp/actions/test_node.h
+++ b/include/behaviortree_cpp/actions/test_node.h
@@ -13,14 +13,14 @@
 
 #pragma once
 
-#include <memory>
-#include <optional>
-#include <string>
-
 #include "behaviortree_cpp/action_node.h"
 #include "behaviortree_cpp/scripting/script_parser.hpp"
 #include "behaviortree_cpp/utils/timer_queue.h"
 
+#include <memory>
+#include <optional>
+#include <string>
+
 namespace BT
 {
 
diff --git a/src/actions/test_node.cpp b/src/actions/test_node.cpp
index ac5fd11b7..b866690cf 100644
--- a/src/actions/test_node.cpp
+++ b/src/actions/test_node.cpp
@@ -33,8 +33,8 @@ void validateTestNodeStatus(NodeStatus status, StringView source)
 
 EnumsTablePtr createTestNodeEnums(const EnumsTablePtr& base_enums)
 {
-  auto enums = base_enums ? std::make_shared<EnumsTable>(*base_enums)
-                          : std::make_shared<EnumsTable>();
+  auto enums = base_enums ? std::make_shared<EnumsTable>(*base_enums) :
+                            std::make_shared<EnumsTable>();
 
   (*enums)["IDLE"] = static_cast<int>(NodeStatus::IDLE);
   (*enums)["RUNNING"] = static_cast<int>(NodeStatus::RUNNING);
@@ -90,8 +90,8 @@ TestNode::TestNode(const std::string& name, const NodeConfig& config,
   if(!_config->complete_func && !_config->return_status &&
      _config->return_status_script.empty())
   {
-    throw RuntimeError(
-        "TestNode requires one of complete_func, return_status, or return_status_script");
+    throw RuntimeError("TestNode requires one of complete_func, return_status, or "
+                       "return_status_script");
   }
 
   _script_enums = createTestNodeEnums(config.enums);
@@ -170,8 +170,8 @@ NodeStatus TestNode::onCompleted()
   }
   else
   {
-    throw RuntimeError(
-        "TestNode requires one of complete_func, return_status, or return_status_script");
+    throw RuntimeError("TestNode requires one of complete_func, return_status, or "
+                       "return_status_script");
   }
 
   validateTestNodeStatus(status, "completion");
diff --git a/src/bt_factory.cpp b/src/bt_factory.cpp
index c4e9c8e03..f363548fe 100644
--- a/src/bt_factory.cpp
+++ b/src/bt_factory.cpp
@@ -540,7 +540,8 @@ void BehaviorTreeFactory::loadSubstitutionRuleFromJSON(const std::string& json_t
       }
       if(test_config.contains("return_status_script"))
       {
-        config.return_status_script = test_config["return_status_script"].get<std::string>();
+        config.return_status_script =
+            test_config["return_status_script"].get<std::string>();
       }
       if(test_config.contains("async_delay"))
       {
diff --git a/tests/gtest_substitution.cpp b/tests/gtest_substitution.cpp
index 23ef0c074..9bd0f2d18 100644
--- a/tests/gtest_substitution.cpp
+++ b/tests/gtest_substitution.cpp
@@ -65,8 +65,8 @@ TEST(Substitution, Parser)
 
   auto configScript = std::get_if<TestNodeConfig>(&rules.at("actionD"));
   ASSERT_FALSE(configScript->return_status.has_value());
-  ASSERT_EQ(configScript->return_status_script,
-            "(mock_should_fail == true) ? FAILURE : SUCCESS");
+  ASSERT_EQ(configScript->return_status_script, "(mock_should_fail == true) ? FAILURE : "
+                                                "SUCCESS");
   ASSERT_EQ(configScript->failure_script, "branch := 'failure'");
 
   ASSERT_EQ(*std::get_if<std::string>(&rules.at("actionC")), "NotAConfig");
@@ -148,8 +148,7 @@ TEST(Substitution, ScriptedReturnStatusOverridesFixedStatus)
 
   TestNodeConfig test_config;
   test_config.return_status = NodeStatus::SUCCESS;
-  test_config.return_status_script =
-      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.return_status_script = "(mock_should_fail == true) ? FAILURE : SUCCESS";
   test_config.failure_script = "branch := 'failure'";
   factory.addSubstitutionRule("action_A", test_config);
 
@@ -178,8 +177,7 @@ TEST(Substitution, ScriptedReturnStatusAsyncSubstitution)
 
   TestNodeConfig test_config;
   test_config.return_status.reset();
-  test_config.return_status_script =
-      "(mock_should_fail == true) ? FAILURE : SUCCESS";
+  test_config.return_status_script = "(mock_should_fail == true) ? FAILURE : SUCCESS";
   test_config.async_delay = std::chrono::milliseconds(50);
   factory.addSubstitutionRule("action_A", test_config);
 
@@ -188,8 +186,8 @@ TEST(Substitution, ScriptedReturnStatusAsyncSubstitution)
       std::async(std::launch::async, [&tree]() { return tree.tickWhileRunning(); });
 
   auto status = future.wait_for(std::chrono::seconds(5));
-  ASSERT_NE(status, std::future_status::timeout)
-      << "Tree hung! tickWhileRunning did not complete within 5 seconds";
+  ASSERT_NE(status, std::future_status::timeout) << "Tree hung! tickWhileRunning did not "
+                                                    "complete within 5 seconds";
   ASSERT_EQ(future.get(), NodeStatus::SUCCESS);
 }
 

From cec469511980f6736fcca2c93ba79d8d6c38279a Mon Sep 17 00:00:00 2001
From: Pepe <pepe@ross-robotics.co.uk>
Date: Thu, 2 Apr 2026 23:38:28 +0100
Subject: [PATCH 3/3] Fix cmake Windows / build (windows-latest, Release)

---
 tests/gtest_wakeup.cpp | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/tests/gtest_wakeup.cpp b/tests/gtest_wakeup.cpp
index 0da9eb8bc..f245ba3c1 100644
--- a/tests/gtest_wakeup.cpp
+++ b/tests/gtest_wakeup.cpp
@@ -41,13 +41,15 @@ TEST(WakeUp, BasicTest)
 
   using namespace std::chrono;
 
-  auto t1 = system_clock::now();
+  auto t1 = steady_clock::now();
   tree.tickOnce();
   tree.sleep(milliseconds(200));
-  auto t2 = system_clock::now();
+  auto t2 = steady_clock::now();
 
   auto dT = duration_cast<milliseconds>(t2 - t1).count();
   std::cout << "Woke up after msec: " << dT << std::endl;
 
-  ASSERT_LT(dT, 25);
+  // The wake-up should interrupt the 200 ms sleep well before the timeout,
+  // but leave enough headroom for scheduler jitter on loaded CI runners.
+  ASSERT_LT(dT, 100);
 }