coeus

coeus is a python client implementation of the json-message protocol for remote (Tcp) integration tests.

Installation

coeus is meant to be added as a requirement to your python unit-test project. Simply add a reference to coeus-test.

pip install coeus-test

Getting Started

Glossary

Client: A class for connecting via TCP to the server application.

Message: A specific json format (prototcol) defining the communication.

TestEntity: An abstract concept for an entity that exists in the server application. Usually accessed via it's ID.

Client Setup

The client must connect to the server application via an IP and port. You can invoke a connection as follows:

import client

cli = client.Client(tcp_port=31203)
cli.connect()

By default, it will attempt to connect with ip: 127.0.0.1.

Commands

Commands are specific blocking calls that are sent to the server, then waits to receive a message. Every command has a response.

Commands do not handle any validation of message received from unity client.

import commands

Query Commands

query_entity_is_registered

This command asks the unity application about the state of an entity.

Usage

result = commands.query_entity_is_registered(cli, "myEntityId")

Response

{
    "type" : "query.entity.isRegistered",
    "payload": {
        "result" : true | false
    }
}

Await Commands

await_entity_registered

This command blocks until a specific state is reached for the entitiy. By default, it will block until the entity was registered. If the command exceeds the specified timeout, it continue with a failure.

Usage

// is_registered, timeout_seconds optional...
result = commands.await_entity_registered(cli, "myEntityId", is_registered=True, timeout_seconds=60)

Response

{
    "type":"await.continue",
    "payload": {
        "success":true|false
    }
}

Fetch Commands

fetch_entity

This command asks the server to serialize the TestEntity and send it.

Usage

result = commands.fetch_entity(cli, "myEntityId")

Success Response

{
    "type":"fetch.entity",
    "payload": {
        "test_entity" : {...} | null
    }
}

Invoke Commands

invoke_entity_method

This command allows the python unit-test to invoke a method on the server"s TestEntity and return the result.

Usage

parameters = {
    "statName":"score"
}
result = commands.invoke_entity_method(cli, "myEntityId", "GetPlayerStat", parameters)

In the C# code, this will look for a method with the following signature:

public int GetPlayerStat(IDynamicObject parameters)
{
    var statName = parameters.GetValue<string>("statName");
    ...

    return stat;
}

Response

{
    "type":"invoke.entity.method",
    "payload": {
        "is_error" : false,
        "error_message" : null,
        "result" : 32
    }
}

If there is a C# exception, then the error_message will contain the exceptions message.

Assertions

The commands do not validate the response from the server. To easily do this, use the assertions.

import assertions

...
# Fails assert if False returned from response...
assertions.assert_entity_is_registered(cli, "myEntityId")

# Fails if timeout exceeded...
assertions.assert_await_entity_registered(cli, "myEntityId")

# Fails if the test_entity is None...
result = assertions.assert_fetch_entity(cli, "myEntityId")

# Fails if is_error == True, AssertException with message provided...
result = assert_invoke_entity_method(cli, "myEntityId", "GetPlayerStat", ...)