Class DockerFixture

An Xunit test fixture used to manage a local Docker daemon within unit tests.

note

The DockerComposeFixture and DockerFixture fixtures are not compatible with each other. You may only use one of these at a time.

Inheritance

object

TestFixture

ComposedFixture

DockerFixture

Implements

ITestFixture

Inherited Members

ComposedFixture.AddFixture<TFixture>(string, TFixture, Action<TFixture>, int)

ComposedFixture.AddServiceFixture<TService>(string, NeonServiceFixture<TService>, Func<TService>, ServiceMap, TimeSpan, int)

ComposedFixture.Start(Action)

ComposedFixture.Children

ComposedFixture.this[string]

ComposedFixture.this[int]

ComposedFixture.Count

ComposedFixture.GetEnumerator()

TestFixture.IsDisposed

TestFixture.InAction

TestFixture.IsRunning

TestFixture.CheckDisposed()

TestFixture.CheckWithinAction()

TestFixture.Dispose()

TestFixture.OnRestart()

TestFixture.State

Namespace: Neon.Xunit

Assembly: Neon.Xunit.dll

Syntax

public class DockerFixture : ComposedFixture, ITestFixture

Remarks

note

IMPORTANT: The base Neon TestFixture implementation DOES NOT support parallel test execution. You need to explicitly disable parallel execution in all test assemblies that rely on thesex test fixtures by adding a C# file called AssemblyInfo.cs with:

[assembly: CollectionBehavior(DisableTestParallelization = true, MaxParallelThreads = 1)]

and then define your test classes like:

public class MyTests : IClassFixture<DockerFixture>, IDisposable
{
    [Collection(TestCollection.NonParallel)]
    [CollectionDefinition(TestCollection.NonParallel, DisableParallelization = true)]
    [Fact]
    public void Test()
    {
    }
}

This fixture resets the state of the local Docker daemon before and after the test runner executes the tests in a test class by removing all containers and services as well as swarm items such as secrets, configs and networks.

note

This fixture works only for local Docker instances that ARE NOT members of a multi-node cluster as a safety measure to help avoid the possiblity of accidentially wiping out a production cluster.

note

The fixture Reset() method does not purge images from the target test node for performance reasons. This can be a problem if you're testing container and you need to ensure that the latest image is downloaded from the registry first. You can call ClearImages() to accomplish this or PullImage(string) to pull a specific image from the registry.

This fixture is pretty easy to use. Simply have your test class inherit from Xunit.IClassFixture<TFixture> and add a public constructor that accepts a DockerFixture as the only argument. Then you can call it's Start(Action) method within the constructor and optionally have your custom Action use the fixture to initialize swarm services, networks, secrets, etc.

This fixture provides several methods for managing the cluster state. These may be called within the test class constructor's action method, within the test constructor but outside of the action, or within the test methods:

Local Machine DNS	LocalMachineHosts
Docker	DockerExecute(string) DockerExecute(params object[])
Configs	ClearConfigs(bool) CreateConfig(string, byte[], string[]) CreateConfig(string, string, string[]) ListConfigs(bool) RemoveConfig(string)
Containers	ClearContainers(bool) ListContainers(bool) RemoveContainer(string) RunContainer(string, string, string[], string[], string[])
Images	ClearImages() PullImage(string)
Networks	ClearNetworks(bool) CreateNetwork(string, string[]) ListNetworks(bool) RemoveNetwork(string)
Secrets	ClearSecrets(bool) CreateSecret(string, byte[], string[]) CreateSecret(string, string, string[]) ListSecrets(bool) RemoveSecret(string)
Services	ClearServices(bool) CreateService(string, string, string[], string[], string[]) ListServices(bool) InspectService(string, bool) RemoveService(string) RestartService(string) RollbackService(string) UpdateService(string, string[])
Stacks	ClearStacks(bool) DeployStack(string, string, string[], TimeSpan, TimeSpan) ListStacks(bool) RemoveStack(string)
Volumes	ClearVolumes(bool)

note

DockerFixture derives from ComposedFixture so you can use AddFixture<TFixture>(string, TFixture, Action<TFixture>, int) to add additional fixtures within your custom initialization action for advanced scenarios.

There are two basic patterns for using this fixture.

initialize once

The basic idea here is to have your test class initialize the swarm once within the test class constructor inside of the initialize action with common state and services that all of the tests can access. This will be quite a bit faster than reconfiguring the swarm at the beginning of every test and can work well for many situations but it assumes that your test methods guarantee that running any test in any order will not impact the results of subsequent tests. A good example of this is a series of read-only tests against a service or database.

initialize every test

For common scenarios where the swarm must be reset before every test, you can call Reset() within the test class constructor (but outside of the custom initialization Action to reset the swarm state before the next test method is invoked.

Constructors

DockerFixture()

Constructs the fixture.

Declaration

public DockerFixture()

DockerFixture(bool)

Used for derived classes that need to disable the Reset() call on construction

Declaration

protected DockerFixture(bool reset = false)

Parameters

Type	Name	Description
bool	reset	Optionally calls Reset() when the reference count is zero.

Fields

DockerNetworks

Identifies the built-in Docker networks. These networks will not be returned by ListNetworks(bool) and cannot be deleted.

Declaration

protected static HashSet<string> DockerNetworks

Field Value

Type	Description
HashSet<string>

Properties

ClearDelay

Some Docker clear operations appear to take a few moments to complete. This delay will be added afterwards in an attempt to address this.

Declaration

public static TimeSpan ClearDelay { get; }

Property Value

Type	Description
TimeSpan

LocalMachineHosts

Returns an integrated HostsFixture that can be used to manage DNS entries in the local machine's DNS hosts file.

Declaration

public HostsFixture LocalMachineHosts { get; }

Property Value

Type	Description
HostsFixture

Methods

ClearConfigs(bool)

Removes all swarm configs.

Declaration

public void ClearConfigs(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster configs as well.

Remarks

By default, this method will not remove core cluster configs whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearContainers(bool)

Removes all running containers.

Declaration

public void ClearContainers(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster containers as well.

Remarks

By default, this method will not remove core cluster containers whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearImages()

Removes all unreferenced images from the target test node. Reset() does not do this for performance reasonse but tests may use this method if necessary.

Declaration

public virtual void ClearImages()

Remarks

note

Using this may result in very slow test performance, especially since it will purge a local copy of neon-cli if present. This means this and any other test images (like Couchbase) will need to be downloaded again after every reset.

We highly recommend that you use PullImage(string) to ensure that the desired images are up-to-date rather than using ClearImages().

ClearNetworks(bool)

Removes all swarm networks.

Declaration

public void ClearNetworks(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster networks as well.

Remarks

By default, this method will not remove core cluster networks whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearSecrets(bool)

Removes all swarm secrets.

Declaration

public void ClearSecrets(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster secrets as well.

Remarks

By default, this method will not remove cluster cluster secrets whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearServices(bool)

Removes all deployed services.

Declaration

public void ClearServices(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster services as well.

Remarks

By default, this method will not remove core cluster services whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearStacks(bool)

Removes all deployed stacks.

Declaration

public void ClearStacks(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster stacks as well.

Remarks

By default, this method will not remove core cluster stacks whose names begin with neon-. You can remove these too by passing removeSystem=true.

ClearVolumes(bool)

Removes all swarm volumes.

Declaration

public void ClearVolumes(bool removeSystem = false)

Parameters

Type	Name	Description
bool	removeSystem	Optionally remove core cluster volumes as well.

Remarks

By default, this method will not remove core cluster volumes whose names begin with neon-. You can remove these too by passing removeSystem=true.

CreateConfig(string, byte[], string[])

Creates a Docker config from bytes.

Declaration

public void CreateConfig(string name, byte[] configBytes, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The secret name.
byte[]	configBytes	The secret bytes.
string[]	dockerArgs	Optional arguments to be passed to the docker config create ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

CreateConfig(string, string, string[])

Creates a Docker config from text.

Declaration

public void CreateConfig(string name, string configText, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The secret name.
string	configText	The secret text.
string[]	dockerArgs	Optional arguments to be passed to the docker config create ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

CreateNetwork(string, string[])

Creates a Docker network.

Declaration

public void CreateNetwork(string name, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The network name.
string[]	dockerArgs	Optional arguments to be passed to the docker network create ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

CreateSecret(string, byte[], string[])

Creates a Docker secret from bytes.

Declaration

public void CreateSecret(string name, byte[] secretBytes, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The secret name.
byte[]	secretBytes	The secret bytes.
string[]	dockerArgs	Optional arguments to be passed to the docker secret create ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

CreateSecret(string, string, string[])

Creates a Docker secret from text.

Declaration

public void CreateSecret(string name, string secretText, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The secret name.
string	secretText	The secret text.
string[]	dockerArgs	Optional arguments to be passed to the docker secret create ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

CreateService(string, string, string[], string[], string[])

Creates a Docker service.

Declaration

public void CreateService(string name, string image, string[] dockerArgs = null, string[] serviceArgs = null, string[] env = null)

Parameters

Type	Name	Description
string	name	The service name.
string	image	Specifies the service image.
string[]	dockerArgs	Optional arguments to be passed to the docker service create ... command.
string[]	serviceArgs	Optional arguments to be passed to the service.
string[]	env	Optional environment variables to be passed to the service, formatted as NAME=VALUE or just NAME.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

DeployStack(string, string, string[], TimeSpan, TimeSpan)

Deploys a Docker stack.

Declaration

public void DeployStack(string name, string composeYaml, string[] dockerArgs = null, TimeSpan timeout = default, TimeSpan convergeTime = default)

Parameters

Type	Name	Description
string	name	The stack name.
string	composeYaml	The compose-file YAML text.
string[]	dockerArgs	Optional arguments to be passed to the docker secret create ... command.
TimeSpan	timeout	Optionally specifies the maximum time to wait for service tasks to start (defaults to 5 minutes).
TimeSpan	convergeTime	Optionally specifies the time to wait after the service tasks have been started for the tasks to initialize. This defaults to 5 seconds which is the same time that Docker waits for Swarm services to converge.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.
TimeoutException	Thrown if the stack tasks were not deployed after waiting timeout.

Dispose(bool)

Releases all associated resources.

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	Pass true if we're disposing, false if we're finalizing.

Overrides

ComposedFixture.Dispose(bool)

DockerExecute(params object[])

Executes an arbitrary docker CLI command passing unformatted arguments and returns the results.

Declaration

public virtual ExecuteResponse DockerExecute(params object[] args)

Parameters

Type	Name	Description
object[]	args	The docker command arguments.

Returns

Type	Description
ExecuteResponse	The ExecuteResponse.

Remarks

This method formats any arguments passed so they will be suitable for passing on the command line by quoting and escaping them as necessary.

note

This method is defined as virtual so that derived classes can modify how Docker is called. For example, the HiveFixture class implemented in another assembly will override this to run the docker within a cluster using neon-cli.

DockerExecute(string)

Executes an arbitrary docker CLI command passing a pre-formatted argument string and returns the results.

Declaration

public virtual ExecuteResponse DockerExecute(string argString)

Parameters

Type	Name	Description
string	argString	The docker command arguments.

Returns

Type	Description
ExecuteResponse	The ExecuteResponse.

Remarks

This method assumes that the single string argument passed is already formatted as required to pass on the command line.

note

This method is defined as virtual so that derived classes can modify how Docker is called. For example, the HiveFixture class implemented in another assembly will override this to run the docker within a cluster using neon-cli.

EnsureReset()

Called by TestFixture to ensure that Docker is reset after an interrupted test run.

Declaration

public static void EnsureReset()

~DockerFixture()

Finalizer.

Declaration

protected ~DockerFixture()

InspectService(string, bool)

Inspects a service, returning details about its current state.

Declaration

public ServiceDetails InspectService(string name, bool strict = false)

Parameters

Type	Name	Description
string	name	The service name.
bool	strict	Optionally specify strict JSON parsing.

Returns

Type	Description
ServiceDetails	The ServiceDetails.

ListConfigs(bool)

Returns information about the current swarm configs.

Declaration

public List<DockerFixture.ConfigInfo> ListConfigs(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster configs whose names start with neon-.

Returns

Type	Description
List<DockerFixture.ConfigInfo>	A list of DockerFixture.ConfigInfo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

ListContainers(bool)

Returns information about the current Docker containers.

Declaration

public List<DockerFixture.ContainerInfo> ListContainers(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster containers whose names start with neon-.

Returns

Type	Description
List<DockerFixture.ContainerInfo>	A list of DockerFixture.ContainerInfo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

ListNetworks(bool)

Returns information about the current swarm networks.

Declaration

public List<DockerFixture.NetworkInfo> ListNetworks(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster networks whose names start with neon-.

Returns

Type	Description
List<DockerFixture.NetworkInfo>	A list of DockerFixture.NetworkInfo.

Remarks

note

This method DOES NOT include built-in Docker networks such as bridge, docker_gwbridge, host, ingress, or none in the listed networks.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

ListSecrets(bool)

Returns information about the current swarm secrets.

Declaration

public List<DockerFixture.SecretInfo> ListSecrets(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster secrets whose names start with neon-.

Returns

Type	Description
List<DockerFixture.SecretInfo>	A list of DockerFixture.SecretInfo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

ListServices(bool)

Returns information about the current swarm services.

Declaration

public List<DockerFixture.ServiceInfo> ListServices(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster services whose names start with neon-.

Returns

Type	Description
List<DockerFixture.ServiceInfo>	A list of DockerFixture.ServiceInfo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

ListStacks(bool)

Returns information about the current swarm stacks.

Declaration

public List<DockerFixture.StackInfo> ListStacks(bool includeSystem = false)

Parameters

Type	Name	Description
bool	includeSystem	Optionally include core built-in cluster stacks whose names start with neon-.

Returns

Type	Description
List<DockerFixture.StackInfo>	A list of DockerFixture.StackInfo.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

PullImage(string)

Pulls a specific image to the target test node.

Declaration

public virtual void PullImage(string image)

Parameters

Type	Name	Description
string	image	The image name.

RemoveConfig(string)

Removes a Docker config.

Declaration

public void RemoveConfig(string name)

Parameters

Type	Name	Description
string	name	The config name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RemoveContainer(string)

Removes a Docker container.

Declaration

public void RemoveContainer(string name)

Parameters

Type	Name	Description
string	name	The container name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RemoveNetwork(string)

Removes a Docker network.

Declaration

public void RemoveNetwork(string name)

Parameters

Type	Name	Description
string	name	The network name.

Remarks

note

This method DOES NOT allow the removal of built-in Docker networks such as bridge, docker_gwbridge, host, ingress, or none in the listed networks.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.
NotSupportedException	Thrown for built-in Docker networks.

RemoveSecret(string)

Removes a Docker secret.

Declaration

public void RemoveSecret(string name)

Parameters

Type	Name	Description
string	name	The secret name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RemoveService(string)

Removes a Docker service.

Declaration

public void RemoveService(string name)

Parameters

Type	Name	Description
string	name	The service name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RemoveStack(string)

Removes a Docker stack.

Declaration

public void RemoveStack(string name)

Parameters

Type	Name	Description
string	name	The stack name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

Reset()

Resets the local Docker daemon by clearing all swarm services and state as well as removing all containers.

Declaration

public override void Reset()

Overrides

ComposedFixture.Reset()

Remarks

note

This method does not reset the Docker images on the test node for performance reasons. You can call ClearImages() from your tests if required.

note

As a safety measure, this method ensures that the local Docker instance IS NOT a member of a multi-node swarm to avoid wiping out production clusters by accident.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.
InvalidOperationException	Thrown if the local Docker instance is a member of a multi-node swarm.

RestartService(string)

Restarts a Docker service.

Declaration

public void RestartService(string name)

Parameters

Type	Name	Description
string	name	The service name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RollbackService(string)

Rolls back a Docker service.

Declaration

public void RollbackService(string name)

Parameters

Type	Name	Description
string	name	The service name.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

RunContainer(string, string, string[], string[], string[])

Creates a Docker container.

Declaration

public void RunContainer(string name, string image, string[] dockerArgs = null, string[] containerArgs = null, string[] env = null)

Parameters

Type	Name	Description
string	name	The container name.
string	image	Specifies the container image.
string[]	dockerArgs	Optional arguments to be passed to the docker service create ... command.
string[]	containerArgs	Optional arguments to be passed to the service.
string[]	env	Optional environment variables to be passed to the container, formatted as NAME=VALUE or just NAME.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

UpdateService(string, string[])

Updates a Docker service.

Declaration

public void UpdateService(string name, string[] dockerArgs = null)

Parameters

Type	Name	Description
string	name	The service name.
string[]	dockerArgs	Arguments to be passed to the docker service update ... command.

Exceptions

Type	Condition
ObjectDisposedException	Thrown if the fixture has been disposed.

Implements

ITestFixture

Extension Methods

IEnumerableExtensions.IsEmpty<T>(IEnumerable<T>, Func<T, bool>)

IEnumerableExtensions.SelectRandom<T>(IEnumerable<T>, int)