swittest protocol

The communication between swittest and switcloud leverages the switcloud-api-py packages.

The communication between swittest and the system under test or swittest and swittest-probe leverages a proprietary protocol.

Messages

The communication between swittest and the system under test relies on TCP/IP connection. It is therefore important to protect this communication against interruptions, latency and any inconveniency that could occur during data transmission in one direction or the other. To do so, and to not over-complicate things for now, we use a very simple protocol consisting in a 64 bits magic number and a 32 bits payload length indicator.

A typical message would then look like:

[MAGIC NUMBER][LENGTH][PAYLOAD]
    64 bit     32 bit    var

Info

The magic number we use is 7377697474657374 (hex)

The payload is a JSON encoded message with a mandatory header for synchronization and a command specific payload.

The header object is composed of the following elements:

• xid: 32-bit unsigned int, unique exchange identifier. This field is optional but if present in the request, it should be present in the response.
• mid: Message ID, mandatory. See list below. The value 0 is reserved for alert messages (e.g. client cannot understand the request at all).

The payload is mandatory and contains at least a status object. The other fields/objects are message-dependent.

The status object is composed of the following elements:

• code: The error code. Mandatory.
• message: The associated error message. Optional.

Below are a couple of request/response examples:

• Request:

{
    "header": {
      "xid": 1,
      "mid": 1000
    },
    "payload": {
        "mydata": "randomstring"
    }
}

• Response:

{
   "header": {
      "xid": 1,
      "mid": 2000
    },
    "payload": {
        "status": {
            "code": 27,
            "message": "Invalid 'mydata' parameter"
        },
    }
}

Message IDs

Here is the list of supported message IDs

Note

All mid are 32-bit unsigned integers comprised between 1000 and 2999 (included). A request's mid is in the range 1000-1999. A response's mid is in the range 2000-2999.

Message	Request ID	Response ID	Status ID
Alert			0
Get POI ID	1001	2001
Set switcloud credentials	1002	2002
Start payment	1003	2003

Error codes

Error codes are application-dependent. 0 means OK, any other positive value is an error.

Messages description

Get POI ID

The "Get POI ID" request will be sent by swittest immediately after a POI or a probe connects to the service.

Info

To reconcile a POI under test with the probe with which it should communicate, both will provide the same POI ID in the response to this command.

Below an example of a request issued by the service:

{
    "header": {
        "xid": 1,
        "mid": 1001
    }
}

Below an example of a positive response issued by a POI or a probe:

{
    "header": {
      "xid": 1,
      "mid": 2001
    },
    "payload": {
        "status": {
            "code": 0
        },
        "poi_id": "019529cd-9418-7071-8703-04a0657f524a"
    }
}

Set switcloud credentials

Before each test run (one or several tests), swittest will send the switcloud connection details to the POI. The request looks as follows:

{
    "header": {
        "xid": 2,
        "mid": 1002
    },
    "payload": {
        "switcloud_url": "https://switcloud.switstack.io:8000",
        "client_id": "my_client_id",
        "client_secret": "my_client_secret"
    }
}

Below an example of a positive response issued by a POI:

{
    "header": {
        "xid": 2,
        "mid": 2002
    },
    "payload": {
        "status": {
            "code": 0
        }
    }
}

Start payment

To start a payment, we use the following request:

{
    "header": {
        "xid": 3,
        "mid": 1003
    },
    "payload": {
        "payment_id": "3f9ccd8a-43a5-4ecc-97cb-77ae07058f6c", (optional)
        "vcard_data": "...", (optional)
    }
}

Note

When a POI is capable of full-virtualization (for instance with moka inside), the "start payment" request will contain both payment_id and vcard_data. If not (e.g. a card emulation probe is used), both the POI and the probe will receive a "start payment" request, each request containing either the payment_id (for the POI) or the vcard_data (for the probe).

Below an example of a positive response issued by a POI or a probe:

{
    "header": {
        "xid": 3,
        "mid": 2003
    },
    "payload": {
        "status": {
            "code": 0
        }
    }
}

Alert

In case a client cannot parse the request at all (format error, etc...) the client should send an alter message to the server. The message looks like follows:

{
    "header": {
        "mid": 0
    },
    "payload": {
        "status": {
            "code": 27,
            "message": "Unrecognized format (erroneous JSON)"
        }
    }
}