RawSocket Built-ins

RawSocket Built-ins open a raw socket connection to any host on any port, as well as send and receive messages to and from the service.

Configuration

Syntax

RawSocketServers {
  <name String> {
    host = <String>
    port = <Number>
  }
...
}

Parameters

• name - The name assigned to the raw socket server

• host - The IP address or host name of the raw socket server

• port - The port that the raw socket server listens on

Example

RawSocketServers {
  "myPC" {
    host = "127.0.0.1"
    port = 5687
  }
  "otherPC" {
    host = "192.168.1.1"
    port = 4365
  }
}

Open a RawSocket Session

In order to send a message, a RawSocket session first needs to be opened.

Syntax

<session RawSocketSession>
    := RawSocket.openSession(<socketServerConfiguration String>)

Returns
The RawSocket session.

Parameter

• socketServerConfiguration - The name of the raw socket server, as assigned in the configuration file

Example

telnetSession := RawSocket.openSession("myPC")

In the example above, a RawSocket session is opened to the "myPC" server.

Send Text

This function sends a string via the session to the socket server.

Syntax

<session RawSocketSession>.send(<text String>)

Parameter

• session - The RawSocket session

• text - The content of the message being sent to the socket server

Example

telnetSession.send("login")

In the example above, the message "login" is sent to the RawSocket server.

Read Until Function

This receives characters via the session from the socket server until a sequence of characters arrives that matches the string defined in the text parameter. The characters (including the text) received up to the point in time when the text has been received will be stored in the context variable. If the string has not been received within the timeout, the function will throw an exception and the step will fail.

Important!

• If the string has not been received within a specified timeout but should not fail, the readUntilSafe() function can be used instead.

• If only the format but not the content of the information from the raw socket connection is known, the Read Until (Regex) should be used instead.

Syntax

<returnValue RawSocketResult>
    := <session RawSocketSession>.readUntil(<text String>, <timeoutMillis Number>)

Returns
A string containing data from the RawSocket until the specified <text> is read. The result string that is returned will contain the data from the RawSocket up to and including the specified string <text> that was given as a parameter. If the RawSocket data does not contain the specified string <text>, then a RuntimeException is thrown.

Parameters

• session - The RawSocketSession to read from

• text - The content to be matched

  • Once this exact sequence of characters have been received, the RawSocket server will stop looking for them

• timeoutMillis - The number of milliseconds to wait for the match condition to be fulfilled

Example

telnetSession.send("login")
result := telnetSession.readUntil("OK", 10000)

In the example above, the client sends a "login" message and waits until the server has sent a string containing "OK". If it is not received within 10 seconds, the step will fail.

Read Until Safe

This function is used instead of readUntil to avoid exceptions thrown in case of timeouts.

• If only the format but not the content of the information from the raw socket connection is known, the Read Until Safe (Regex) should be used instead.

Syntax

<returnValue RawSocketResult>
    := <session RawSocketSession>.readUntilSafe(<endStr String>,
    <timeoutMillis Number>)

Returns

• success - A boolean indicating whether or not the expected string arrived within the timeout.

• result - A string containing the expected string and all the characters that arrived before the timeout.

  • The result will be null if success is false.

Parameters

• session - The RawSocketSession to read from

• endStr - The string to be waited for

• timeoutMillis - The number of milliseconds to wait for the endStr

Example

  for i in range(0, nrOfTries)
      session.send("login")
      result := session.readUntilSafe("OK", 10000)
      if (result.success) then
          return result.result
      end
  end
  assert false

In the example above, the client sends "login" to the server and waits for the server to send "OK" within 10 seconds. If the client does not receive "OK", it will repeat trying to do that for nrOfTries times. If it receives it within the nrOfTries, it will succeed and the test case will pass. If it does not receive the "OK" within nrOfTries, then the test case will fail.

Disconnect Function

This function is used to disconnect the session to the socket server.

Syntax

<session RawSocketSession>.disconnect()

Parameter

• session - The Rawsocket session

Example

telnetSession.disconnect()

Read Until (Regex)

This receives characters via the session from the socket server until a sequence of characters arrives that matches the string defined in the regex parameter. The characters (including the regex) received up to the point in time when the text has been received will be stored in the context variable.

• If the string has not been received within the timeout, the function will throw an exception and the step will fail. The readRegExSafe function can be used instead to specify a timeout.

Syntax

<resultValue String> := conn.readRegEx(<regex String>, <timeoutMillis Number>)

Returns

• A string that contains the regex that has been expected. If no string matching the regex has been found within the timeout, the test case will end with an exception on this operation.

Parameters

• regex - The regular expression matched against the received string from the raw socket connection

• timeoutMillis - The number of milliseconds to wait for the regex condition to be fulfilled

Example In the example below, a string must be received that contains 4 comma-separated decimal numbers. Additionally, a line break is expected after the last number.

result := conn.readRegEx("\\d+,\\d+,\\d+,\\d+\\R")

Note: The \\R in the example above is particularly important: If the expected line break is not specified in the regular expression, the expression will match as soon as the first digit after the third comma is received, even if the fourth number would contain more digits.

Read Until Safe (Regex)

This function is used instead of readRegEx to avoid exceptions thrown in case of timeouts.

Syntax

<returnValue RawSocketResult> := conn.readRegExSafe(<regex String>, <timeoutMillis Number>)

Returns

• success - A Boolean indicating whether or not the regex has been found within the timeout.

• result - If success is true, this element contains the string matching the regex.

Parameters

• regex - The regular expression matched against the received string from the raw socket connection

• timeoutMillis - The number of milliseconds to wait for the regex condition to be fulfilled

Example In the example below, a string must be received within 5 seconds that contains four comma-separated decimal numbers. After the last number, a line break is expected.

result := conn.readRegExSafe("\\d+,\\d+,\\d+,\\d+\\R", 5000)

Note: The \\R in the example above is particularly important: If the expected line break is not specified in the regular expression, the expression will match as soon as the first digit after the third comma is received, even if the fourth number would contain more digits.