Click or drag to resize

DockerFixture Class

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

Namespace:  Neon.Xunit
Assembly:  Neon.Xunit (in Neon.Xunit.dll) Version: 2.1.0
Syntax
public class DockerFixture : ComposedFixture

The DockerFixture type exposes the following members.

Constructors
Properties
  NameDescription
Public propertyChildren
Returns the subfixtures.
(Inherited from ComposedFixture.)
Public propertyStatic memberClearDelay
Some Docker clear operations appear to take a few moments to complete. This delay will be added afterwards in an attempt to address this.
Public propertyCount
Returns the number of fixtures in the set.
(Inherited from ComposedFixture.)
Protected propertyInAction
Returns true if the Start(Action) method is running.
(Inherited from TestFixture.)
Protected propertyIsDisposed
Returns true if the instance has been disposed.
(Inherited from TestFixture.)
Public propertyIsRunning
Returns true if the fixture has been initialized.
(Inherited from TestFixture.)
Public propertyItemInt32
Returns the fixture at the specified index (based on the order the fixture was added.
(Inherited from ComposedFixture.)
Public propertyItemString
Returns the named test fixture.
(Inherited from ComposedFixture.)
Public propertyLocalMachineHosts
Returns an integrated HostsFixture that can be used to manage DNS entries in the local machine's DNS hosts file.
Public propertyState
Used by unit test classes to persist arbitrary name/value information across individual unit tests.
(Inherited from TestFixture.)
Top
Methods
  NameDescription
Public methodAddFixtureTFixture
Adds a named ITestFixture.
(Inherited from ComposedFixture.)
Public methodAddServiceFixtureTService (Inherited from ComposedFixture.)
Protected methodCheckDisposed
Verifies that the fixture instance has not been disposed.
(Inherited from TestFixture.)
Protected methodCheckWithinAction
Verifies that the fixture instance's Start(Action) method is executing.
(Inherited from TestFixture.)
Public methodClearConfigs
Removes all swarm configs.
Public methodClearContainers
Removes all running containers.
Public methodClearImages
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.
Public methodClearNetworks
Removes all swarm networks.
Public methodClearSecrets
Removes all swarm secrets.
Public methodClearServices
Removes all deployed services.
Public methodClearStacks
Removes all deployed stacks.
Public methodClearVolumes
Removes all swarm volumes.
Public methodCreateConfig(String, Byte, String)
Creates a Docker config from bytes.
Public methodCreateConfig(String, String, String)
Creates a Docker config from text.
Public methodCreateNetwork
Creates a Docker network.
Public methodCreateSecret(String, Byte, String)
Creates a Docker secret from bytes.
Public methodCreateSecret(String, String, String)
Creates a Docker secret from text.
Public methodCreateService
Creates a Docker service.
Public methodDeployStack
Deploys a Docker stack.
Public methodDispose
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from TestFixture.)
Protected methodDispose(Boolean)
Releases all associated resources.
(Overrides ComposedFixtureDispose(Boolean).)
Public methodDockerExecute(Object)
Executes an arbitrary docker CLI command passing unformatted arguments and returns the results.
Public methodDockerExecute(String)
Executes an arbitrary docker CLI command passing a pre-formatted argument string and returns the results.
Public methodStatic memberEnsureReset
Called by TestFixture to ensure that Docker is reset after an interrupted test run.
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Protected methodFinalize
Finalizer.
(Overrides ComposedFixtureFinalize.)
Public methodGetEnumerator
Enumerates the named test fixtures in the set.
(Inherited from ComposedFixture.)
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodInspectService
Inspects a service, returning details about its current state.
Public methodListConfigs
Returns information about the current swarm configs.
Public methodListContainers
Returns information about the current Docker containers.
Public methodListNetworks
Returns information about the current swarm networks.
Public methodListSecrets
Returns information about the current swarm secrets.
Public methodListServices
Returns information about the current swarm services.
Public methodListStacks
Returns information about the current swarm stacks.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodOnRestart

Called when an already started fixture is being restarted. This provides the fixture an opportunity to do some custom initialization. This base method does nothing.

Note Note
This method is intended only for use by test fixture implementations. Unit tests or test fixtures should never call this directly.
(Inherited from TestFixture.)
Public methodPullImage
Pulls a specific image to the target test node.
Public methodRemoveConfig
Removes a Docker config.
Public methodRemoveContainer
Removes a Docker container.
Public methodRemoveNetwork
Removes a Docker network.
Public methodRemoveSecret
Removes a Docker secret.
Public methodRemoveService
Removes a Docker service.
Public methodRemoveStack
Removes a Docker stack.
Public methodReset
Resets the local Docker daemon by clearing all swarm services and state as well as removing all containers.
(Overrides ComposedFixtureReset.)
Public methodRestartService
Restarts a Docker service.
Public methodRollbackService
Rolls back a Docker service.
Public methodRunContainer
Creates a Docker container.
Public methodStart
Starts the fixture if it hasn't already been started including invoking the optional Action when the first time Start(Action) is called for a fixture instance.
(Inherited from ComposedFixture.)
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodUpdateService
Updates a Docker service.
Top
Fields
  NameDescription
Protected fieldStatic memberDockerNetworks
Identifies the built-in Docker networks. These networks will not be returned by ListNetworks(Boolean) and cannot be deleted.
Top
Remarks
Note Note

IMPORTANT: The Neon TestFixture implementation DOES NOT support parallel test execution because fixtures may impact global machine state like starting a Couchbase Docker container, modifying the local DNS hosts file or managing a Docker Swarm or cluster.

You should explicitly disable parallel execution in all test assemblies that rely on test fixtures by adding a C# file called AssemblyInfo.cs with:

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

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 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 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 IClassFixture 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 tha action, or within the test methods:

Local Machine DNSLocalMachineHosts
DockerDockerExecute(String)
DockerExecute(Object)
ConfigsClearConfigs(Boolean)
CreateConfig(String, Byte, String)
CreateConfig(String, String, String)
ListConfigs(Boolean)
RemoveConfig(String)
ContainersClearContainers(Boolean)
ListContainers(Boolean)
RemoveContainer(String)RunContainer(String, String, String, String, String)
ImagesClearImages
PullImage(String)
NetworksClearNetworks(Boolean)
CreateNetwork(String, String)
ListNetworks(Boolean)
RemoveNetwork(String)
SecretsClearSecrets(Boolean)
CreateSecret(String, Byte, String)
CreateSecret(String, String, String)
ListSecrets(Boolean)
RemoveSecret(String)
ServicesClearServices(Boolean)
CreateService(String, String, String, String, String)
ListServices(Boolean)
InspectService(String, Boolean)
RemoveService(String)
RestartService(String)
RollbackService(String)
UpdateService(String, String)
StacksClearStacks(Boolean)
DeployStack(String, String, String, TimeSpan, TimeSpan)
ListStacks(Boolean)
RemoveStack(String)
VolumesClearVolumes(Boolean)

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.
Thread Safety
Instance members of this type are safe for multi-threaded operations.
See Also