diff --git a/src/NUnit.Engine.Api/ITestAgentProvider.cs b/src/NUnit.Engine.Api/ITestAgentProvider.cs new file mode 100644 index 0000000..9d69dcd --- /dev/null +++ b/src/NUnit.Engine.Api/ITestAgentProvider.cs @@ -0,0 +1,104 @@ +// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt + +using System; + +namespace NUnit.Engine.Services +{ + /// + /// Provides test agents suitable for a and accepts + /// their return when the caller no longer requires them. + /// + /// + /// + /// This contract applies to in-process, local-process and remote agents. It does + /// not require the caller to own a process or perform a particular registration + /// handshake. The caller does not need to know how a provider obtains its agents + /// or what resources it manages. The provider is responsible for its agents + /// and their resources. + /// + /// + /// The caller is responsible for returning each acquired agent through the same + /// provider. Capability queries do not transfer that responsibility to the caller; + /// see for their initialization and discovery limits. + /// + /// + public interface ITestAgentProvider : ITestAgentInfo + { + /// + /// Determines whether the provider can currently supply an agent suitable + /// for running the provided test package. + /// + /// A TestPackage + /// True if the provider can currently supply a compatible agent. + /// + /// + /// This query does not return an agent or make the caller responsible for + /// returning one. It does not guarantee that no extension or agent implementation + /// is loaded or instantiated internally. Depending on the information supplied + /// by an extension, the provider may use declared metadata or instantiate the + /// extension to determine its capabilities. Other implementations may need to + /// initialize provider resources or contact another host. + /// + /// + /// A successful query does not reserve an agent. Availability may change before + /// is called, so the caller must still handle acquisition failure. + /// The provider remains responsible for resources created while evaluating the query. + /// + /// + bool IsAgentAvailable(TestPackage package); + + /// + /// Acquires an agent suitable for the criteria specified in a . + /// + /// The test package to be run + /// The acquired agent, which must be returned through this provider. + /// If the package is invalid. + /// + /// No compatible agent is available. Call first + /// to check suitability, while allowing for availability to change before acquisition. + /// + /// + /// + /// Successful acquisition makes the caller responsible for returning this exact + /// agent reference using . The provider retains responsibility + /// for its underlying implementation and resources; acquiring an agent does not + /// imply that the caller owns its process, transport or deployment. + /// + /// + /// If acquisition throws, the provider remains responsible for resources created + /// during the failed attempt. + /// + /// + ITestAgent GetAgent(TestPackage package); + + /// + /// Returns a previously acquired test agent to the provider that supplied it. + /// + /// An agent previously acquired by a call to . + /// + /// The reference was not acquired from this provider or was previously returned. + /// + /// + /// + /// Return the exact reference through the same provider that supplied it so that + /// ownership bookkeeping remains consistent. After successfully returning the + /// agent, the caller must not continue using the reference. The provider remains + /// responsible for its agents and their resources. + /// + /// + /// A stop request, a closed connection or disposal of a runner is not confirmation + /// that the agent was returned. If returning an agent fails, preserve its association + /// with the originating provider. Further attempts to return it must use that provider. + /// A failed call does not guarantee that no work was performed, so the caller must + /// not assume that repeating it is harmless. + /// + /// + /// Successfully returning an agent does not by itself prove that it terminated or that + /// external resources, including deployed files, are no longer in use. Before + /// removing resources used by an agent, the responsible provider must establish + /// that the agent no longer needs them. This applies to all provider types. + /// + /// + void ReturnAgent(ITestAgent agent); + } +}