fix: add Signals support for unit tests with controllable task flushing

mcollovati · mcollovati · commit 119a0569e16a · 2025-10-13T07:38:23.000+02:00
Introduce a test-only TestSignalEnvironment that captures all Signals-related tasks when no VaadinSession/VaadinService is available (e.g., background threads). Tests can deterministically flush these tasks via new runPendingSignalsTasks helpers in BaseUIUnitTest. Fixes #1968
diff --git a/vaadin-testbench-unit-junit5/src/test/java/com/example/base/signals/SignalsView.java b/vaadin-testbench-unit-junit5/src/test/java/com/example/base/signals/SignalsView.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2000-2025 Vaadin Ltd
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ * See <https://vaadin.com/commercial-license-and-service-terms> for the full
+ * license.
+ */
+
+package com.example.base.signals;
+
+import java.util.concurrent.CompletableFuture;
+
+import com.vaadin.flow.component.ComponentEffect;
+import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.component.html.NativeButton;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.router.Route;
+import com.vaadin.signals.NumberSignal;
+import com.vaadin.signals.Signal;
+
+@Route("signals")
+public class SignalsView extends Div {
+
+    public final NativeButton incrementButton;
+    public final NativeButton quickBackgroundTaskButton;
+    public final NativeButton slowBackgroundTaskButton;
+    public final Span counter;
+    public final NumberSignal numberSignal;
+
+    public SignalsView() {
+        numberSignal = new NumberSignal();
+        Signal<String> computedSignal = numberSignal
+                .mapIntValue(counter -> "Counter: " + counter);
+        incrementButton = new NativeButton("Increment",
+                ev -> numberSignal.incrementBy(1.0));
+        counter = new Span("Counter: -");
+        ComponentEffect.bind(counter, computedSignal, Span::setText);
+
+        quickBackgroundTaskButton = new NativeButton("Quick background task",
+                event -> {
+                    CompletableFuture.runAsync(
+                            () -> numberSignal.incrementBy(10.0),
+                            CompletableFuture.delayedExecutor(100,
+                                    java.util.concurrent.TimeUnit.MILLISECONDS));
+                });
+        slowBackgroundTaskButton = new NativeButton("Quick background task",
+                event -> CompletableFuture.runAsync(() -> {
+                    ComponentEffect.effect(counter, () -> {
+                        try {
+                            Thread.sleep(1000);
+                        } catch (InterruptedException e) {
+                            Thread.currentThread().interrupt();
+                            throw new RuntimeException(e);
+                        }
+                        numberSignal.incrementBy(10.0);
+                    });
+                }));
+
+        add(incrementButton, quickBackgroundTaskButton,
+                slowBackgroundTaskButton, counter);
+    }
+}
diff --git a/vaadin-testbench-unit-junit5/src/test/java/com/vaadin/testbench/unit/SignalsTest.java b/vaadin-testbench-unit-junit5/src/test/java/com/vaadin/testbench/unit/SignalsTest.java
@@ -0,0 +1,100 @@
+/*
+ * Copyright (C) 2000-2025 Vaadin Ltd
+ *
+ * This program is available under Vaadin Commercial License and Service Terms.
+ *
+ * See <https://vaadin.com/commercial-license-and-service-terms> for the full
+ * license.
+ */
+
+package com.vaadin.testbench.unit;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.TimeUnit;
+
+import com.example.base.signals.SignalsView;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.Timeout;
+
+import com.vaadin.flow.component.ComponentEffect;
+import com.vaadin.flow.component.UI;
+
+@ViewPackages(packages = "com.example.base.signals")
+@Timeout(10)
+public class SignalsTest extends UIUnitTest {
+
+    @Test
+    void attachedComponent_triggerSignal_effectEvaluatedSynchronously() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+
+        test(view.incrementButton).click();
+        Assertions.assertEquals("Counter: 1", counterTester.getText());
+    }
+
+    @Test
+    void detachedComponent_triggerSignal_effectEvaluatedOnAttach() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+        view.counter.removeFromParent();
+        Assertions.assertFalse(counterTester.isUsable());
+
+        test(view.incrementButton).click();
+        Assertions.assertEquals("Counter: 0", view.counter.getText());
+
+        view.add(view.counter);
+        Assertions.assertEquals("Counter: 1", view.counter.getText());
+    }
+
+    @Test
+    void detachedComponent_triggerEffect_effectEvaluatedAsynchronously() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+        UI ui = UI.getCurrent();
+        UI.setCurrent(null);
+
+        ComponentEffect.effect(ui,
+                () -> view.counter.setText("Counter: async"));
+        runPendingSignalsTasks();
+
+        UI.setCurrent(ui);
+        Assertions.assertEquals("Counter: async", view.counter.getText());
+    }
+
+    @Test
+    void attachedComponent_triggerSignalFromNonUIThread_effectEvaluatedAsynchronously() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+        CompletableFuture.runAsync(() -> {
+            view.numberSignal.incrementBy(10.0);
+        });
+        runPendingSignalsTasks();
+        Assertions.assertEquals("Counter: 10", counterTester.getText());
+    }
+
+    @Test
+    void attachedComponent_triggerSignalFromNonUIThreadThroughComponentEffect_effectEvaluatedAsynchronously() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+        test(view.quickBackgroundTaskButton).click();
+        runPendingSignalsTasks(300, TimeUnit.MILLISECONDS);
+        Assertions.assertEquals("Counter: 10", counterTester.getText());
+    }
+
+    @Test
+    void attachedComponent_slowEffect_effectEvaluatedAsynchronously() {
+        var view = navigate(SignalsView.class);
+        var counterTester = test(view.counter);
+        Assertions.assertEquals("Counter: 0", counterTester.getText());
+        test(view.slowBackgroundTaskButton).click();
+        runPendingSignalsTasks();
+        Assertions.assertEquals("Counter: 10", counterTester.getText());
+    }
+
+}
diff --git a/vaadin-testbench-unit-junit5/src/test/resources/vaadin-featureflags.properties b/vaadin-testbench-unit-junit5/src/test/resources/vaadin-featureflags.properties
@@ -0,0 +1,10 @@
+#
+# Copyright (C) 2000-2025 Vaadin Ltd
+#
+# This program is available under Vaadin Commercial License and Service Terms.
+#
+# See <https://vaadin.com/commercial-license-and-service-terms> for the full
+# license.
+#
+
+com.vaadin.experimental.flowFullstackSignals=true
diff --git a/vaadin-testbench-unit-shared/src/main/java/com/vaadin/testbench/unit/BaseUIUnitTest.java b/vaadin-testbench-unit-shared/src/main/java/com/vaadin/testbench/unit/BaseUIUnitTest.java
@@ -21,6 +21,7 @@
 import java.util.Properties;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -31,13 +32,16 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import com.vaadin.experimental.FeatureFlags;
 import com.vaadin.flow.component.Component;
 import com.vaadin.flow.component.HasElement;
 import com.vaadin.flow.component.Key;
 import com.vaadin.flow.component.KeyModifier;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.router.HasUrlParameter;
 import com.vaadin.flow.router.RouteParameters;
+import com.vaadin.flow.server.VaadinService;
+import com.vaadin.flow.server.VaadinSession;
 import com.vaadin.pro.licensechecker.Capabilities;
 import com.vaadin.pro.licensechecker.Capability;
 import com.vaadin.pro.licensechecker.LicenseChecker;
@@ -71,6 +75,8 @@ public abstract class BaseUIUnitTest {
     protected static final Map<Class<?>, Class<? extends ComponentTester>> testers = new HashMap<>();
     protected static final Set<String> scanned = new HashSet<>();
 
+    private TestSignalEnvironment signalsTestEnvironment;
+
     static {
         testers.putAll(scanForTesters("com.vaadin.flow.component"));
         Properties properties = new Properties();
@@ -180,6 +186,19 @@ protected static synchronized Routes discoverRoutes(
     protected void initVaadinEnvironment() {
         scanTesters();
         MockVaadin.setup(discoverRoutes(), MockedUI::new, lookupServices());
+        initSignalsSupport();
+    }
+
+    protected void initSignalsSupport() {
+        VaadinService service = VaadinService.getCurrent();
+        if (service == null) {
+            throw new IllegalStateException(
+                    "Cannot initialize Signals support because VaadinService is not available");
+        }
+        if (FeatureFlags.get(service.getContext())
+                .isEnabled(FeatureFlags.FLOW_FULLSTACK_SIGNALS.getId())) {
+            signalsTestEnvironment = TestSignalEnvironment.register();
+        }
     }
 
     /**
@@ -223,6 +242,10 @@ Set<String> scanPackages() {
      * Tears down mocked Vaadin.
      */
     protected void cleanVaadinEnvironment() {
+        if (signalsTestEnvironment != null) {
+            signalsTestEnvironment.unregister();
+            signalsTestEnvironment = null;
+        }
         MockVaadin.tearDown();
     }
 
@@ -512,6 +535,70 @@ protected static void roundTrip() {
                 .runExecutionsBeforeClientResponse();
     }
 
+    /**
+     * Processes all pending Signals tasks with a default max wait time of 100
+     * milliseconds. This is a convenience method for tests that need to wait
+     * for asynchronous Signal effects to complete.
+     *
+     * <p>
+     * When Signals are triggered from background threads or non-UI contexts,
+     * their effects are enqueued to simulate asynchronous processing. This
+     * method allows tests to flush and execute all such pending tasks
+     * synchronously, ensuring deterministic behavior in unit tests.
+     *
+     * <p>
+     * If any {@link VaadinSession} lock is held by the current thread, it is
+     * temporarily released during the wait to allow background threads to
+     * acquire the lock and enqueue tasks.
+     *
+     * <p>
+     * If Signals support is not enabled (via the {@code FLOW_FULLSTACK_SIGNALS}
+     * feature flag), this method does nothing.
+     *
+     * @see #runPendingSignalsTasks(long, TimeUnit)
+     * @see TestSignalEnvironment#runPendingTasks(long, TimeUnit)
+     */
+    protected final void runPendingSignalsTasks() {
+        runPendingSignalsTasks(100, TimeUnit.MILLISECONDS);
+    }
+
+    /**
+     * Processes all pending Signals tasks, waiting up to the specified timeout
+     * for tasks to arrive. This method is essential for testing asynchronous
+     * Signal effects triggered from background threads or non-UI contexts.
+     *
+     * <p>
+     * When Signals are triggered from background threads or non-UI contexts,
+     * their effects are enqueued to simulate asynchronous processing. This
+     * method allows tests to flush and execute all such pending tasks
+     * synchronously, ensuring deterministic behavior in unit tests.
+     *
+     * <p>
+     * The timeout applies only to waiting for the first task to arrive. Once
+     * the first task is found, all remaining tasks in the queue are processed
+     * immediately without additional waiting. If any {@link VaadinSession} lock
+     * is held by the current thread, it is temporarily released during the wait
+     * to allow background threads to acquire the lock and enqueue tasks.
+     *
+     * <p>
+     * If Signals support is not enabled (via the {@code FLOW_FULLSTACK_SIGNALS}
+     * feature flag), this method does nothing.
+     *
+     * @param maxWaitTime
+     *            the maximum time to wait for the first task to arrive in the
+     *            given time unit. If &lt;= 0, returns immediately if no tasks
+     *            are available.
+     * @param unit
+     *            the time unit of the timeout value
+     * @see TestSignalEnvironment#runPendingTasks(long, TimeUnit)
+     */
+    protected final void runPendingSignalsTasks(long maxWaitTime,
+            TimeUnit unit) {
+        if (this.signalsTestEnvironment != null) {
+            this.signalsTestEnvironment.runPendingTasks(maxWaitTime, unit);
+        }
+    }
+
     /**
      * Detects the component type for the given tester from generic declaration,
      * by inspecting class hierarchy to resolve the concrete type for
diff --git a/vaadin-testbench-unit-shared/src/main/java/com/vaadin/testbench/unit/TestSignalEnvironment.java b/vaadin-testbench-unit-shared/src/main/java/com/vaadin/testbench/unit/TestSignalEnvironment.java
