-
Notifications
You must be signed in to change notification settings - Fork 48
RammbockUserGuide
Rammbock is a generic protocol testing library for Robot Framework. Rammbock allows you to create protocol and message templates and then mock clients and servers sending and receiving these messages. This guide describes how to use Rammbock and its features.
Note that Rammbock is still at Alpha status. We hope to keep the API stable, but at this moment we can not guarantee that there wont be backwards incompatible changes still before the 1.0 release.
Rammbock can be installed with pip using the following command:
pip install robotframework-rammbock
You can also use easy install with the following command:
easy_install robotframework-rammbock
To take the library into use, you should import it with name Rammbock:
Library Rammbock
Servers and clients can be created with Start UDP client and Start UDP server keywords. There are also respective keywords for the TCP protocol. The servers have to be given the address and port they start to listen. For clients giving the host name and port is optional. See the keyword API documentation for details.
All Start * -keywords take a name as optional named argument. This name can be used to define which server or client sends or receives the message, if there are several clients and servers. By default, the latest server or client is used.
When creating servers and clients, you can optionally give them a protocol argument. See Creating a protocol below. If you don't give a protocol to a server or client, then you can only send and receive raw binary with that network node.
Example:
Start server
Start UDP server 127.0.0.1 8282 protocol=GTPV2
Start client
Start UDP client protocol=GTPV2
Connect 127.0.0.1 8282
Rammbock describes messages with protocol and message templates. Each message must conform to a protocol template that is described with New protocol keyword. Protocol template describes the protocol header fields which are same for all messages that belong to that protocol. For example the protocol header for GTPV2-protocol would be following:
define gtpv2 protocol
new protocol gtpv2
u8 flags 0b01001000
u8 messageType
u16 messageLength
u32 tunnelEndpointIdentifier 0
u24 sequenceNumber
u8 spare 0
pdu messageLength-12
end protocol
This describes the GTPV2 as a protocol with first two bytes containing flags and message type. Then next 16 bit unsigned integer contains the message length. Next element is tunnel endpoint identifier that is 4 bytes wide. After tunnel endpoint identifier there is sequence number and of 3 bytes and a spare byte. The last element of the protocol description is the protocol data unit with length of "message length-12". This is because in GTPV2 the message length-field describes the length of the entire message, including the twelve header bytes.
After the protocol has been defined, the Rammbock library will keep it in memory until Reset Rammbock keyword is called. Note that you should define the protocol only once. After the protocol has been defined, you can create clients, servers, and message templates that conform to this protocol.
All protocol definitions have to contain exactly one pdu-element, which has to be the last element in the protocol definition. The length of the pdu-field can reference previous protocol header fields with either + or - operations (for example "previousField + 1" is also a valid length). The length can also be fixed integer number of bytes (for example "42").
After you have defined a protocol, you can describe the individual messages as message templates. Each template describes the fields inside one pdu-field.
A simple example message containing three 2-byte fields (this is not a valid GTPV2 pdu, see the acceptance tests for a real example):
Example request
New message ExampleRequest protocol=GTPV2 messageType:0x0a
u16 firstField 42
u16 secondField 0xcafe
u16 thirdField
This example message template has name ExampleMessage which is only used in logs for pretty printing the messages. The protocol for this message is GTPV2 and the message template also defines a value for one of the protocol header fields (messageType:0x0a). If you look at the protocol definition in earlier listing, you will notice that the messageType-field does not have value defined. You can define values for protocol header fields in the arguments of the New message keyword with syntax field:value.
The fields of the message follow the New message keyword. The firstField has a default value of integer 42 and secondField the hex value 0xcafe. The thirdField however does not have a default value. The value for this field has to be set before the message can be encoded. You can use either Value keyword or arguments to Get message or send message -keywords to set a value for the thirdField.
You can save the message templates for later use with Save template keyword and load them again with Load template.
If you dont want to send the message, but instead just to try encoding it and to access its fields, you can get the message object using Get message keyword. All message fields need to have a defined value before the message can be encoded.
The returned message object allows access to its fields using dot-separated paths. For example to access values from the ExampleRequest defined in Message templates above:
Encode template
Define GTPV2 protocol
Example request
${msg}= Get message thirdField:10
Should be equal as integers ${msg.thirdField.int} 10
Should be equal ${msg.thirdField.hex} 0x0a
Message field values can be converted to integer values with postfix int or to hex values with postfix hex. Table below describes all supported field value conversions.
| Postfix | Result |
| int | Integer value |
| hex | Hexadecimal string |
| bin | Binary string |
| ascii | Field bytes as ascii string (non ascii bytes are ignored) |
| bytes | Raw bytes |
| chars | Raw bytes (same as bytes) |
| tbcd | Telephony Binary Coded Decimal |
| _raw | Raw bytes in transport format (little endian and aligned if needed) |
| name | Field name |
You can send messages using Client sends message or Server sends message. All message fields need to have a defined value before the message can be sent.
Messages are received using Client receives message and Server receives message. If you have defined values for message fields in message template, then Rammbock will automatically validate that the values of the message fields conform to those. See Validation below for more information.
When receiving messages with Client receives message and Server receives message -keywords, the Rammbock automatically validates the message fields against the values given in message template. Optional values can be given inside parenthesis and separated by pipes. If field can have any value at all, the field can be given with trailing colon, but without any parameter. See examples below:
Receive template
Define GTPV2 protocol
Start client
Start server
Example request
Client sends message thirdField:2
${msg}= Server receives message secondField: thirdField:(1|2)
[Teardown] Reset rammbock
In this example we are mocking both the client and the server in order to make it possible to run it independently, but usually we would only be either sending or receiving the message, not both. Here in row "Server receives message" we are telling the validation engine that secondField can have any value and that thirdField can have either value 1 or 2.
Rammbock supports filtering incoming messages based on protocol header fields. By default Client receives message and Server receives message -keywords return the first message from the socket and all protocol header field values defined in the protocol template or given as message parameters are simply ignored. If the * receives message -keywords are given extra argument header_filter, then the received messages are searched for a message where the value of header field given as header_filter value matches that given in message template. See example below.
Example of using header_filter where server waits until it receives a message with messageType field having value 0xba:
Receive template
Define GTPV2 protocol
Start server
New message ExampleForSearching protocol=GTPV2 messageType:0xba
u16 field 42
${msg}= Server receives message header_filter=messageType
[Teardown] Reset rammbock