js: branch-outcome and comparison events for coverage/debug tooling

EventType.BRANCH fires after a conditional construct (if / ternary /
logical short-circuit / nullish / switch case) decides which arm to
take, carrying the boolean outcome. EventType.COMPARE fires when a
comparison operator evaluates, carrying the concrete lhs/op/rhs
operands. Event gains a nullable value slot for these payloads.

Both fire only when a listener is registered - zero overhead
unobserved, matching the existing evalExpr guard pattern.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ptrthomas

karate-js/src/main/java/io/karatelabs/js/CoreContext.java

@@ -134,6 +134,13 @@ void event(EventType type, Node node) {
         }
     }
 
+    void event(EventType type, Node node, Object value) {
+        if (root.listener != null) {
+            Event event = new Event(type, this, node, value);
+            root.listener.onEvent(event);
+        }
+    }
+
     // public api ======================================================================================================
     //
     final CoreContext parent;

karate-js/src/main/java/io/karatelabs/js/Event.java

@@ -30,11 +30,22 @@ public class Event {
     public final EventType type;
     public final Context context;
     public final Node node;
+    /**
+     * Optional payload, present only for event types that carry one —
+     * {@link EventType#BRANCH} (a {@link Boolean} outcome) and
+     * {@link EventType#COMPARE} (an {@code Object[]} of lhs / operator / rhs).
+     */
+    public final Object value;
 
     Event(EventType type, Context context, Node node) {
+        this(type, context, node, null);
+    }
+
+    Event(EventType type, Context context, Node node, Object value) {
         this.type = type;
         this.context = context;
         this.node = node;
+        this.value = value;
     }
 
 }

karate-js/src/main/java/io/karatelabs/js/EventType.java

@@ -30,6 +30,19 @@ public enum EventType {
     STATEMENT_ENTER,
     STATEMENT_EXIT,
     EXPRESSION_ENTER,
-    EXPRESSION_EXIT
+    EXPRESSION_EXIT,
+    /**
+     * Fired after a conditional construct (if / ternary / logical
+     * short-circuit / switch case) decides which arm to take. The event
+     * {@code value} is the {@link Boolean} outcome. Useful for coverage
+     * and debugger tooling.
+     */
+    BRANCH,
+    /**
+     * Fired when a comparison operator evaluates. The event {@code value}
+     * is an {@code Object[]} of {@code [lhs, operator, rhs]} with the
+     * concrete operand values. Useful for coverage and debugger tooling.
+     */
+    COMPARE
 
 }

karate-js/src/main/java/io/karatelabs/js/Interpreter.java

@@ -1461,7 +1461,9 @@ private static Object evalIfStmt(Node node, CoreContext context) {
         if (context.isStopped()) {
             return null;
         }
-        if (Terms.isTruthy(condition)) {
+        boolean taken = Terms.isTruthy(condition);
+        context.event(EventType.BRANCH, node, taken);
+        if (taken) {
             return eval(node.get(4), context);
         } else {
             if (node.size() > 5) {
@@ -1785,6 +1787,9 @@ private static boolean evalLogicExpr(Node node, CoreContext context) {
             return false;
         }
         TokenType logicOp = node.get(1).token.type;
+        if (context.root.listener != null) {
+            context.event(EventType.COMPARE, node, new Object[]{lhs, node.get(1).getText(), rhs});
+        }
         if (Terms.NAN.equals(lhs) || Terms.NAN.equals(rhs)) {
             if (logicOp == NOT_EQ || logicOp == NOT_EQ_EQ) {
                 return true;  // NaN is not equal to anything, including itself
@@ -1811,6 +1816,7 @@ private static Object evalLogicAndExpr(Node node, CoreContext context) {
             return null;
         }
         boolean lhs = Terms.isTruthy(lhsValue);
+        context.event(EventType.BRANCH, node, lhs);
         if (node.get(1).token.type == AMP_AMP) {
             if (lhs) {
                 return eval(node.get(2), context);
@@ -1833,7 +1839,9 @@ private static Object evalLogicNullishExpr(Node node, CoreContext context) {
             return null;
         }
         // ?? returns lhs if it's not null/undefined, otherwise rhs
-        if (lhsValue == null || lhsValue == Terms.UNDEFINED) {
+        boolean defined = lhsValue != null && lhsValue != Terms.UNDEFINED;
+        context.event(EventType.BRANCH, node, defined);
+        if (!defined) {
             return eval(node.get(2), context);
         }
         return lhsValue;
@@ -1845,7 +1853,9 @@ private static Object evalLogicTernExpr(Node node, CoreContext context) {
         if (context.isStopped()) {
             return null;
         }
-        if (Terms.isTruthy(testValue)) {
+        boolean taken = Terms.isTruthy(testValue);
+        context.event(EventType.BRANCH, node, taken);
+        if (taken) {
             return eval(node.get(2), context);
         } else {
             return eval(node.get(4), context);
@@ -2133,7 +2143,9 @@ private static Object evalSwitchStmt(Node node, CoreContext context) {
                     if (context.isStopped()) {
                         return null;
                     }
-                    if (Terms.eq(switchValue, caseValue, true)) {
+                    boolean matched = Terms.eq(switchValue, caseValue, true);
+                    context.event(EventType.BRANCH, caseNode, matched);
+                    if (matched) {
                         found = true;
                     }
                 }

karate-js/src/test/java/io/karatelabs/js/ContextEventsTest.java

@@ -0,0 +1,164 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2025 Karate Labs Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package io.karatelabs.js;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Tests for the {@link EventType#BRANCH} and {@link EventType#COMPARE}
+ * events used by coverage and debugger tooling.
+ */
+class ContextEventsTest {
+
+    static class EventCollector implements ContextListener {
+
+        final List<Event> branches = new ArrayList<>();
+        final List<Event> compares = new ArrayList<>();
+
+        @Override
+        public void onEvent(Event event) {
+            if (event.type == EventType.BRANCH) {
+                branches.add(event);
+            } else if (event.type == EventType.COMPARE) {
+                compares.add(event);
+            }
+        }
+
+        // (line, outcome) pairs for readable assertions, lines 1-based
+        List<String> branchSummary() {
+            List<String> list = new ArrayList<>();
+            for (Event e : branches) {
+                list.add((e.node.getFirstToken().line + 1) + ":" + e.value);
+            }
+            return list;
+        }
+
+    }
+
+    private static EventCollector run(String script, Object input) {
+        Engine engine = new Engine();
+        EventCollector collector = new EventCollector();
+        engine.setListener(collector);
+        engine.put("input", input);
+        engine.eval(script);
+        return collector;
+    }
+
+    @Test
+    void testIfElseBranch() {
+        String script = "if (input > 5) { 'big' } else { 'small' }";
+        EventCollector c = run(script, 10);
+        assertEquals(List.of("1:true"), c.branchSummary());
+        c = run(script, 3);
+        assertEquals(List.of("1:false"), c.branchSummary());
+    }
+
+    @Test
+    void testTernaryBranch() {
+        String script = "var x = input ? 'a' : 'b'";
+        EventCollector c = run(script, true);
+        assertEquals(List.of("1:true"), c.branchSummary());
+        c = run(script, false);
+        assertEquals(List.of("1:false"), c.branchSummary());
+    }
+
+    @Test
+    void testLogicalAndOrBranch() {
+        String script = "var x = input && 'a';\n"
+                + "var y = input || 'b';";
+        EventCollector c = run(script, true);
+        assertEquals(List.of("1:true", "2:true"), c.branchSummary());
+        c = run(script, false);
+        assertEquals(List.of("1:false", "2:false"), c.branchSummary());
+    }
+
+    @Test
+    void testNullishBranch() {
+        String script = "var x = input ?? 'fallback'";
+        EventCollector c = run(script, "value");
+        assertEquals(List.of("1:true"), c.branchSummary());
+        c = run(script, null);
+        assertEquals(List.of("1:false"), c.branchSummary());
+    }
+
+    @Test
+    void testSwitchBranch() {
+        String script = "switch (input) {\n"
+                + "case 'a': 1; break;\n"
+                + "case 'b': 2; break;\n"
+                + "default: 3\n"
+                + "}";
+        EventCollector c = run(script, "b");
+        // first case misses, second matches — no further case tests
+        assertEquals(List.of("2:false", "3:true"), c.branchSummary());
+        c = run(script, "z");
+        assertEquals(List.of("2:false", "3:false"), c.branchSummary());
+    }
+
+    @Test
+    void testCompareOperands() {
+        EventCollector c = run("input >= 25", 22);
+        assertEquals(1, c.compares.size());
+        Object[] operands = (Object[]) c.compares.get(0).value;
+        assertEquals(22, operands[0]);
+        assertEquals(">=", operands[1]);
+        assertEquals(25, operands[2]);
+    }
+
+    @Test
+    void testCompareOperators() {
+        String script = "input < 1; input > 2; input <= 3; input >= 4; input == 5; input === 6; input != 7; input !== 8;";
+        EventCollector c = run(script, 5);
+        assertEquals(8, c.compares.size());
+        List<String> ops = new ArrayList<>();
+        for (Event e : c.compares) {
+            ops.add((String) ((Object[]) e.value)[1]);
+        }
+        assertEquals(List.of("<", ">", "<=", ">=", "==", "===", "!=", "!=="), ops);
+    }
+
+    @Test
+    void testBranchInsideCallbackFiresPerInvocation() {
+        String script = "var count = 0;\n"
+                + "[1, 2, 3].forEach(function(x){ if (x > 1) count++ });\n"
+                + "count";
+        EventCollector c = run(script, null);
+        // one BRANCH per callback invocation, same site
+        assertEquals(List.of("2:false", "2:true", "2:true"), c.branchSummary());
+        assertEquals(3, c.compares.size());
+    }
+
+    @Test
+    void testNoListenerNothingBreaks() {
+        Engine engine = new Engine();
+        Object result = engine.eval("var x = 5 > 3 ? (1 && 2) : 0; x");
+        assertEquals(2, result);
+    }
+
+}