EventSourcingDB.TestContainer (EventSourcingDB v1.0.1)

Using Testcontainers for Testing

Follow the instructions to setup test containers for elixir.

Then you are ready to use the provided TestContainer in your tests:

defmodule YourTest do
  alias EventSourcingDB.TestContainer
  use ExUnit.Case

  import Testcontainers.ExUnit

  container(:esdb, TestContainer.new())

  test "ping", %{esdb: esdb} do
    client = TestContainer.get_client(esdb)

    assert EventSourcingDB.ping(client) == :ok
  end
end

Configuring the Container Instance

By default, TestContainer uses the latest tag of the official EventSourcingDB Docker image. To change that, call the with_image_tag function:

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_image_tag("1.0.0")
)

Similarly, you can configure the port to use and the API token. Call the with_port or the with_api_token function respectively:

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_port(4000)
  |> TestContainer.with_api_token("secret")
)

If you want to sign events, call the with_signing_key function. This generates a new signing and verification key pair inside the container:

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_signing_key()
)

You can retrieve the public key (for verifying signatures) once the container has been started:

verification_key = TestContainer.get_verification_key(esdb)

The verification_key can be passed to Event.verify_signature when verifying events read from the database.

Configuring the Client Manually

In case you need to set up the client yourself, use the following functions to get details on the container:

TestContainer.get_base_url(esdb) returns the full URL of the container
TestContainer.get_mapped_port(esdb) returns the mapped port
TestContainer.get_api_token(esdb) returns the API token

Summary

Functions

get_api_token(container)

Gets the API token for the given container

get_base_url(container)

Generates the base_url for accessing the EventSourcingDB service running within the container.

get_client(container)

Gets the EventSourcingDB client for the given container

get_mapped_port(container)

Returns the port on the host machine where the EventSourcingDB container is listening.

get_verification_key(container)

Returns the Ed25519 public key for verifying event signatures.

new()

Creates a new Testcontainer with default settings - ready for immediate use

with_api_token(config, api_token)

Use a custom api token for the testcontainer

with_image_tag(config, image_tag)

Use a custom image tag or the testcontainer

with_port(config, port)

Use a custom port for the testcontainer

with_signing_key(config)

Enables event signing for the testcontainer by generating an Ed25519 key pair.

Functions

get_api_token(container)

Gets the API token for the given container

Parameters

container: The active EventSourcingDB container instance in the form of a TestContainer struct.

Examples

iex> TestContainer.get_api_token(container)
"secret"

get_base_url(container)

Generates the base_url for accessing the EventSourcingDB service running within the container.

This URL is based on the standard localhost IP and the mapped port for the container.

Parameters

container: The active EventSourcingDB container instance in the form of a TestContainer struct.

Examples

iex> TestContainer.get_base_url(container)
"http://localhost:32768" # This value will be different depending on the mapped port.

get_client(container)

Gets the EventSourcingDB client for the given container

Parameters

container: The active EventSourcingDB container instance in the form of a TestContainer struct.

Examples

iex> TestContainer.get_client(container)
%EventSourcingDB.Client{...}

get_mapped_port(container)

Returns the port on the host machine where the EventSourcingDB container is listening.

get_verification_key(container)

Returns the Ed25519 public key for verifying event signatures.

This key can be passed to EventSourcingDB.Event.verify_signature/2. Only available when the container was created with with_signing_key/1.

new()

Creates a new Testcontainer with default settings - ready for immediate use

with_api_token(config, api_token)

Use a custom api token for the testcontainer

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_api_token("secret")
)

with_image_tag(config, image_tag)

Use a custom image tag or the testcontainer

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_image_tag("1.0.0")
)

with_port(config, port)

Use a custom port for the testcontainer

container(
  :esdb,
  TestContainer.new()
  |> TestContainer.with_port(4000)
)

with_signing_key(config)

Enables event signing for the testcontainer by generating an Ed25519 key pair.

The signing key is used by the server to sign events. The corresponding verification key can be retrieved via get_verification_key/1 after the container has started.