Add scripted return status support for TestNode mocks

Introduce `return_status_script` on TestNodeConfig, allowing a mock's
completion status to be computed at runtime from blackboard state instead
of being fixed. When set, it takes precedence over `return_status`; it may
reference the NodeStatus names (SUCCESS/FAILURE/...) and is rejected if it
resolves to IDLE.

The NodeStatus enum names are injected only into the return_status_script
environment. The pre-existing success_script/failure_script/post_script
continue to evaluate against the node's own enums, so a blackboard entry
named like a status (e.g. "SUCCESS") is not shadowed.

To pay the ABI break only once, TestNode's state is moved behind a PImpl,
so future changes to it no longer alter the layout consumers link against
(mirroring StatusChangeLogger). The new return_status_script field is
appended at the end of TestNodeConfig, preserving the byte offsets of the
existing fields.

Also add JSON validation rejecting a TestNodeConfig with neither a
return_status nor a return_status_script, and a tutorial example
(t15_nodes_mocking_strict_failure) demonstrating the strict-failure flow.

Addresses #995.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

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")

examples/t15_nodes_mocking.cpp

@@ -39,7 +39,7 @@ 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.
  * @param argc
  * @param argv
  * @return

examples/t15_nodes_mocking_strict_failure.cpp

@@ -0,0 +1,143 @@
+#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_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".
+
+*/

include/behaviortree_cpp/actions/test_node.h

@@ -14,15 +14,19 @@
 #pragma once
 
 #include "behaviortree_cpp/action_node.h"
-#include "behaviortree_cpp/scripting/script_parser.hpp"
-#include "behaviortree_cpp/utils/timer_queue.h"
+
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <string>
 
 namespace BT
 {
 
 struct TestNodeConfig
 {
-  /// status to return when the action is completed.
+  /// Status to return when the action is completed.
+  /// If return_status_script is also set, the script takes precedence.
   NodeStatus return_status = NodeStatus::SUCCESS;
 
   /// script to execute when complete_func() returns SUCCESS
@@ -38,14 +42,27 @@ 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;
+
+  /// 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.
+  /// When set, this takes precedence over return_status.
+  ///
+  /// NOTE: kept last to preserve the byte offsets of the fields above.
+  std::string return_status_script;
 };
 
 /**
  * @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)
@@ -73,26 +90,32 @@ class TestNode : public BT::StatefulActionNode
   TestNode(const std::string& name, const NodeConfig& config,
            std::shared_ptr<TestNodeConfig> test_config);
 
+  ~TestNode() override;
+
+  TestNode(const TestNode& other) = delete;
+  TestNode& operator=(const TestNode& other) = delete;
+
+  TestNode(TestNode&& other) = delete;
+  TestNode& operator=(TestNode&& other) = delete;
+
   static PortsList providedPorts()
   {
     return {};
   }
 
 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;
-  ScriptFunction _success_executor;
-  ScriptFunction _failure_executor;
-  ScriptFunction _post_executor;
-  TimerQueue<> _timer;
-  std::atomic_bool _completed = false;
+  // All state lives behind this pointer, so that adding or changing it does not
+  // alter the layout that consumers compile against.
+  struct PImpl;
+  std::unique_ptr<PImpl> _p;
 };
 
 }  // namespace BT