cc

Documentation

Index

• Constants
• type ClientCreationRequest
• type EncRoomOption
• type Instance
  • func NewInstance(cfg *config.ComplementCrypto) *Instance
  • func (i *Instance) ClientTypeMatrix(t *testing.T, ...)
  • func (i *Instance) CreateTestContext(t *testing.T, clientType ...api.ClientType) *TestContext
  • func (i *Instance) Deploy(t *testing.T) *deploy.ComplementCryptoDeployment
  • func (i *Instance) ForEachClientType(t *testing.T, subTest func(t *testing.T, clientType api.ClientType))
  • func (i *Instance) ShouldTest(lang api.ClientTypeLang) bool
  • func (i *Instance) TestMain(m *testing.M, namespace string)
• type TestContext
  • func (c *TestContext) CreateNewEncryptedRoom(t *testing.T, user *User, options ...EncRoomOption) (roomID string)
  • func (c *TestContext) MustCreateClient(t *testing.T, req *ClientCreationRequest) api.TestClient
  • func (c *TestContext) MustLoginClient(t *testing.T, req *ClientCreationRequest) api.TestClient
  • func (c *TestContext) MustRegisterNewDevice(t *testing.T, user *User, newDeviceID string) *User
  • func (c *TestContext) RegisterNewUser(t *testing.T, clientType api.ClientType, localpartSuffix string) *User
  • func (c *TestContext) WithAliceAndBobSyncing(t *testing.T, callback func(alice, bob api.TestClient))
  • func (c *TestContext) WithAliceBobAndCharlieSyncing(t *testing.T, callback func(alice, bob, charlie api.TestClient))
  • func (c *TestContext) WithAliceSyncing(t *testing.T, callback func(alice api.TestClient))
  • func (c *TestContext) WithClientSyncing(t *testing.T, req *ClientCreationRequest, callback func(cli api.TestClient))
  • func (c *TestContext) WithClientsSyncing(t *testing.T, reqs []*ClientCreationRequest, ...)
• type User

Constants

const EncRoomOptions encRoomOptions = 0

A namespace for the various options that may be passed in to CreateNewEncryptedRoom

Types

type ClientCreationRequest

type ClientCreationRequest struct {
	User *User
	Opts api.ClientCreationOpts
	// If true, spawn this client in another process
	Multiprocess bool
}

TestClientCreationRequest is a request to create a new api.Client.

A request is always based on an existing user e.g Alice, Bob, in which case the user ID / password / HS URL will be used. Any options specified in this request are then applied on top e.g PersistentStorage.

type EncRoomOption

type EncRoomOption = func(reqBody map[string]interface{})

An option to customise the behaviour of CreateNewEncryptedRoom

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance represents a test instance.

The instance is the global variable holding onto all data that must be shared between tests, such as the configuration options and the deployed containers.

func NewInstance

func NewInstance(cfg *config.ComplementCrypto) *Instance

func (*Instance) ClientTypeMatrix

func (i *Instance) ClientTypeMatrix(t *testing.T, subTest func(t *testing.T, clientTypeA, clientTypeB api.ClientType))

ClientTypeMatrix enumerates all provided client permutations given by the test client matrix `COMPLEMENT_CRYPTO_TEST_CLIENT_MATRIX`. Creates sub-tests for each permutation and invokes `subTest`. Sub-tests are run in series.

func (*Instance) CreateTestContext

func (i *Instance) CreateTestContext(t *testing.T, clientType ...api.ClientType) *TestContext

CreateTestContext creates a new test context suitable for immediate use. The variadic clientTypes control how many clients are automatically registered:

• 1x clientType = Alice
• 2x clientType = Alice, Bob
• 3x clientType = Alice, Bob, Charlie

You can then either login individual users using testContext.MustLoginClient or use the helper functions testContext.WithAliceAndBobSyncing which will automatically create js/rust clients and start sync loops for you, along with handling cleanup.

func (*Instance) Deploy

func (i *Instance) Deploy(t *testing.T) *deploy.ComplementCryptoDeployment

Deploy all backend servers if they do not already exist. Calling this multiple times will return the same deployment.

Tests will rarely use this function directly, preferring to use TestContext. See Instance.CreateTestContext

func (*Instance) ForEachClientType

func (i *Instance) ForEachClientType(t *testing.T, subTest func(t *testing.T, clientType api.ClientType))

ForEachClientType enumerates all known client implementations and creates sub-tests for each. Sub-tests are run in series. Always defaults to `hs1`.

func (*Instance) ShouldTest

func (i *Instance) ShouldTest(lang api.ClientTypeLang) bool

ShouldTest returns true if this language should be tested.

func (*Instance) TestMain

func (i *Instance) TestMain(m *testing.M, namespace string)

TestMain is the entry point for running a test suite with this Instance. The function signature matches the standard Go test suite TestMain()

type TestContext

type TestContext struct {
	Deployment    *deploy.ComplementCryptoDeployment
	RPCBinaryPath string
	RPCInstance   atomic.Int32

	// Alice is defined if at least 1 clientType is provided to CreateTestContext.
	Alice *User
	// Bob is defined if at least 2 clientTypes are provided to CreateTestContext.
	Bob *User
	// Charlie is defined if at least 3 clientTypes are provided to CreateTestContext.
	Charlie *User
}

TestContext provides a consistent set of variables which most tests will need access to. The variables are suitable for a single test.

func (*TestContext) CreateNewEncryptedRoom

func (c *TestContext) CreateNewEncryptedRoom(
	t *testing.T,
	user *User,
	options ...EncRoomOption,
) (roomID string)

CreateNewEncryptedRoom calls creator.MustCreateRoom with the correct m.room.encryption state event.

options is a set of EncRoomOption that may be provided using methods on EncRoomOptions: - Preset*: the preset argument passed to createRoom (default: "private_chat") - Invite: a list of usernames to invite to the room (default: empty list) - RotationPeriodMsgs: value of the rotation_period_msgs param (default: omitted)

func (*TestContext) MustCreateClient

func (c *TestContext) MustCreateClient(t *testing.T, req *ClientCreationRequest) api.TestClient

MustCreateClient creates an api.Client from an existing Complement client and the specified client type. Additional options can be set to configure the client beyond that of the Complement client e.g to add persistent storage.

func (*TestContext) MustLoginClient

func (c *TestContext) MustLoginClient(t *testing.T, req *ClientCreationRequest) api.TestClient

MustLoginClient is the same as MustCreateClient but also logs in the client.

func (*TestContext) MustRegisterNewDevice

func (c *TestContext) MustRegisterNewDevice(t *testing.T, user *User, newDeviceID string) *User

MustRegisterNewDevice logs in a new device for this client, else fails the test.

func (*TestContext) RegisterNewUser

func (c *TestContext) RegisterNewUser(t *testing.T, clientType api.ClientType, localpartSuffix string) *User

RegisterNewUser registers a new user on the homeserver. The user ID will include the localpartSuffix.

Returns a User with a single device which represents the Complement client for this registration. This User can then be passed to other functions to login on new test devices.

func (*TestContext) WithAliceAndBobSyncing

func (c *TestContext) WithAliceAndBobSyncing(t *testing.T, callback func(alice, bob api.TestClient))

WithAliceAndBobSyncing is a helper function which creates rust/js clients and automatically logs in Alice & Bob and starts a sync loop for both. For more customisation, see WithClientsSyncing.

The callback function is invoked after this, and cleanup functions are called on your behalf when the callback function ends.

func (*TestContext) WithAliceBobAndCharlieSyncing

func (c *TestContext) WithAliceBobAndCharlieSyncing(t *testing.T, callback func(alice, bob, charlie api.TestClient))

WithAliceBobAndCharlieSyncing is a helper function which creates rust/js clients and automatically logs in Alice, Bob and Charlie and starts a sync loop for all. For more customisation, see WithClientsSyncing.

The callback function is invoked after this, and cleanup functions are called on your behalf when the callback function ends.

func (*TestContext) WithAliceSyncing

func (c *TestContext) WithAliceSyncing(t *testing.T, callback func(alice api.TestClient))

WithAliceSyncing is a helper function which creates a rust/js client and automatically logs in Alice and starts a sync loop for her. For more customisation, see WithClientSyncing.

The callback function is invoked after this, and cleanup functions are called on your behalf when the callback function ends.

func (*TestContext) WithClientSyncing

func (c *TestContext) WithClientSyncing(t *testing.T, req *ClientCreationRequest, callback func(cli api.TestClient))

WithClientSyncing is a helper function which creates a test client and automatically logs in the user and starts a sync loop for them. Additional options can be specified via ClientCreationRequest, including setting the client up as a multiprocess client, with persistent storage, etc.

The callback function is invoked after this, and cleanup functions are called on your behalf when the callback function ends.

func (*TestContext) WithClientsSyncing

func (c *TestContext) WithClientsSyncing(t *testing.T, reqs []*ClientCreationRequest, callback func(clients []api.TestClient))

WithClientsSyncing is a helper function which creates multiple test clients and automatically logs in all of them and starts a sync loop for all of them. Additional options can be specified via ClientCreationRequest, including setting clients up as a multiprocess client, with persistent storage, etc.

All clients are logged in FIRST before syncing any one of them. As Login() is supposed to block until all keys are uploaded, this guarantees that device keys / OTKs / etc exist prior to syncing. This means it is not neccessary to synchronise device list changes between these clients.

The callback function is invoked after this, and cleanup functions are called on your behalf when the callback function ends.

type User

type User struct {
	*client.CSAPI
	// remember the client types that were supplied so we can seamlessly create the right
	// test client when WithAliceSyncing/etc are called.
	ClientType api.ClientType
}

User represents a single matrix user ID e.g @alice:example.com, along with the complement device for this user.