WebSocket handling

[apreg]

I'm looking for guidance on how to properly handle WebSocket messages in Serenity/JS.

Let’s say I send a WebSocket message in an Interaction with a specific ID. Then, in a separate Question, I wait for the corresponding response message.

The problem is:

• The Question needs to know the message ID generated in the Task.

• This means I have to store the ID somewhere (for example in the actor's notes).

• Since sending and waiting are separated, there's a risk of missing the message if it arrives before the Question starts listening.

One possible solution would be introducing a message cache that stores incoming WebSocket messages so they can be matched later.

However, I’m wondering whether this is the right architectural approach.

For example, CallAnApi's Send interaction waits for the HTTP response internally. Would it make sense for a SendWebSocketMessage interaction to also wait for the matching response message?

The complication is that the matcher logic is not always a simple ID comparison. Sometimes the matching criteria are more complex, which would require passing a matcher function into the Task. That starts to feel like an antipattern, since it mixes orchestration logic with message-matching logic.

What is the recommended way in Serenity/JS to:

• correlate outgoing WebSocket messages with incoming responses,

• avoid race conditions,

• and keep the solution aligned with Screenplay principles?

[jan-molak]

That sounds like a good candidate for a custom Ability.

In Serenity/JS, abilities are the right place to encapsulate any state or integrations your actors need. Instead of trying to pass messages around indirectly, you can give the actor an ability that records incoming messages, and then have your Question read from it.

1. Custom ability

import { Ability } from '@serenity-js/core';

export class ReceiveMessages extends Ability {

    private messages: any[] = [];

    static using(source: SomeMessageSource) {
        const ability = new ReceiveMessages();

        source.onMessage(message => ability.record(message));

        return ability;
    }

    private record(message: any) {
        this.messages.push(message);
    }

    latest() {
        return this.messages[this.messages.length - 1];
    }

    all() {
        return [...this.messages];
    }
}

The key idea is that this ability becomes the single place responsible for collecting messages.

2. Assign the ability to an actor

actorCalled('Alice').whoCan(
    ReceiveMessages.using(myMessageSource),
);

3. Question that reads from the ability

import { Question } from '@serenity-js/core';

export const LastReceivedMessage = () =>
    Question.about('last received message', actor =>
        ReceiveMessages.as(actor).latest()
    );
    

Why this works well

• Separation of concerns: the ability handles integration and state, the question just queries it
• Reusability: you can ask different questions (latest, matching criteria, count, etc.)
• Test clarity: your scenarios stay expressive and aligned with the Screenplay pattern

If your use case involves filtering (e.g. “message with type X”), you can extend the ability with query methods or keep the filtering logic in the Question, depending on how reusable you want it to be.

[apreg]

Thanks @jan-molak. One thing worth making explicit, because I think it's the root of our scaling problem:

Your ReceiveMessages is intentionally a pure observer — the transport (SomeMessageSource) lives outside the ability, and the ability only records inbound messages.

What we built is a full WebSocket client ability, modelled after CallAnApi from @serenity-js/rest. The motivation is the same as for REST: we want our actors to be able to set up state and exercise the backend directly over WS — create/seed/subscribe to resources — without going through the UI. That means the ability has to own the socket lifecycle (connect / send / buffer-first waitForMessage(predicate) / disconnect), so that send and receive can share the same buffer and avoid races.

The problem is that in our domain, a single persona talks to several backend services over different WebSocket connections. Each needs its own socket and its own message buffer (we don't want messages from one service leaking into a wait for a reply from another). Because an Ability is keyed by class per actor, our only working option was to give each endpoint its own actor — which means the actor name stops being a business persona and becomes a routing label for a WS channel, and scenarios that legitimately need to coordinate across services have to switch personas mid-scenario.

What's the recommended Screenplay-idiomatic way to model one persona, multiple long-lived WebSocket connections, each with its own buffer, when the ability itself owns the transport?