WebSockets

Open WebSocket connections to your services, send messages on them, and check the messages they receive and how they close.

Register a connection with the {word} websocket with the following properties:: it opens there and then, with the headers and subprotocol the table gives, and belongs to the scenario, which closes it when it ends.

• What is received is checked like the messages of queues and topics: received a message where: takes a table of paths into a JSON message and the values they have, and received a message containing {string} looks for text in any message. The checks wait, 10 seconds unless within {duration} says otherwise, and look at every message the connection received.
• A connection the server closes fails a check that is still waiting at once, saying why; was closed with code {int} checks the code it closed with.
• Secrets stay secret: ${env:..} values in the URL and the headers, such as a token, are masked in logs and failures.

Add it to a project with axx pack add websocket.

Steps

websocket.connect

Given the {word} websocket with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Open a WebSocket connection under a name. It belongs to the scenario, which closes it when it ends.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
url	the address, ws:// or wss://	required
header.<name>	a header of the opening request, such as header.Authorization
subprotocol	the subprotocols to offer, separated by commas
asyncapi	an AsyncAPI document, a file of the project or a URL, that the messages both ways follow: every message a scenario sends there, and every message a check finds, is checked against it (with the asyncapi pack)

Values are expanded (${env:..}, ${sys:..}); what ${env:..} references expand to is masked everywhere.

Example:

Given the tracking websocket with the following properties:
  | url | ws://localhost:8400/portal/track/PX-LIV-5701/live |

Since 0.1.5.

websocket.send

When a message is sent to the {word} websocket:
  """
  ...
  """

Send the doc string as a text message on the connection.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When a message is sent to the tracking websocket:
  """
  {"follow": "PX-LIV-5701"}
  """

Since 0.1.5.

websocket.send.file

When the {filepath} message is sent to the {word} websocket

Send the file of the project as a text message on the connection.

Parameter	Takes	For example
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the tracking/follow-PX-LIV-5701.json message is sent to the tracking websocket

Since 0.1.5.

websocket.received

Then [[within {duration} ]]the {word} websocket received a message where:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the connection received a JSON message with those values. The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the message (a field name, a dotted path or a JSONPath) and the value it has, compared as text: null for null and undefined for absent.

Variants, the parts in [[...]] said or left out:

• the {word} websocket received a message where:
• within {duration} the {word} websocket received a message where:

Example:

Then within 20s the tracking websocket received a message where:
  | reference | PX-LIV-5701      |
  | status    | OUT_FOR_DELIVERY |

Since 0.1.5.

websocket.received.text

Then [[within {duration} ]]the {word} websocket received a message containing {string}

Check that the connection received a message containing the text. The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} websocket received a message containing {string}
• within {duration} the {word} websocket received a message containing {string}

Example:

Then the tracking websocket received a message containing 'PX-LIV-5701'

Since 0.1.5.

websocket.closed

Then [[within {duration} ]]the {word} websocket was closed with code {int}

Check that the server closed the connection with that close code, such as 1000 (normal) or 1008 (a policy it breaks). The check waits for it: 10 seconds, or within {duration}.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{int}	a whole number	200, 3

Variants, the parts in [[...]] said or left out:

• the {word} websocket was closed with code {int}
• within {duration} the {word} websocket was closed with code {int}

Example:

Then the tracking websocket was closed with code 1008

Since 0.1.5.