Vaadin Flow

The test-embedding module contains integration tests for embedding Vaadin Flow. The module structure is organized by execution mode and environment:

Generic Embedding Modules

These modules run the same core tests but differ in configuration:

• test-embedding-generic: Runs in development mode.
• test-embedding-production: Runs in production mode.
• test-embedding-generic-compatibility: Runs in compatibility (Bower) mode using HTML imports.
• test-embedding-production-compatibility: Runs in production mode using compatibility (Bower) mode.

All four generic modules depend on embedding-test-assets, which provides the test classes and the classes under test. The HTML pages for these tests are located in test-embedding/webapp.

Theme Variant Modules

Because a package containing embeddable components can only have one theme, modules leveraging theme variants are separated:

• test-embedding-theme-variant
• test-embedding-theme-variant-compatibility

The flow-tests suite is organized along two independent axes to ensure clear testing coverage without duplication:

1. Settings → module: Modules are split based on the specific build or deployment configuration they require (e.g., production mode, vaadinrouter, pnpm, springsecurity). A module should ideally pin exactly one specific setting.
2. Feature → package: Within a module, tests are organized into Java packages based on the framework feature they exercise (e.g., routing, dom, components).

Key Principles:

• Source Home: Every Integration Test (IT) has exactly one "home" (one module + one package) where its source code lives.
• Permutations via Reuse: To test a feature under a different setting (e.g., testing routing in production mode), the specialized module reuses the test-jar from the feature's "home" module rather than duplicating the source code.
• Minimal Specialized Modules: Specialized modules contain only tests that specifically exercise their pinned setting. Generic feature tests are housed in test-default.

Instead of traditional listener APIs, expose observable state using the Signal<T> pattern.

Best Practices:

• Naming: Suffix accessors with Signal (e.g., localeSignal(), valueSignal(), activeSignal()).
• Implementation: Back the signal with a private ValueSignal<T> and expose it as read-only using valueSignal.asReadonly().
• Performance: Cache the read-only wrapper in a field. Do not call .asReadonly() inside the getter, as it allocates a new lambda every time.
• Defaults: Never seed a signal with null. Use a sentinel enum (e.g., UNKNOWN) or a dedicated record (e.g., Pending) to represent missing data.
• Usage: Use .get() when inside a reactive context (subscribes) and .peek() when outside (snapshot).

public class MyComponent {
    private final ValueSignal<String> statusSignal = new ValueSignal<>("UNKNOWN");
    private final Signal<String> readOnlyStatus = statusSignal.asReadonly();

    public Signal<String> statusSignal() {
        return readOnlyStatus;
    }
}

To manage streaming and state changes between the browser and the server, use a pattern where DOM events act as the transport and Signal acts as the state.

Event-to-Signal Bridging

1. The client dispatches a CustomEvent (e.g., vaadin-xxx-position or vaadin-xxx-error).
2. The server-side facade listens for the DOM event, extracts the detail record, and writes it to a private ValueSignal.
3. Applications subscribe to the Signal rather than the DOM event.

Client-Initiated State Changes

For state changes that occur without a server request (e.g., network status, window resize):

1. The client dispatches a vaadin-xxx-change event on document.body.
2. The facade registers a listener on ui.getElement() and forwards the detail to the appropriate signal.

Managing Async Browser Handles

When a browser API returns an opaque ID (like watchPosition()), do not round-trip the ID itself. Instead:

1. Pre-generate a UUID on the server.
2. Pass the UUID as an executeJs parameter.
3. The client-side wrapper stores a mapping of Map<key, browserId>.
4. Subsequent operations (like clearWatch(key)) use the server-generated key to look up the actual browser ID.