diff --git a/src/NUnit.Engine.Api/ITestAgentProvider.cs b/src/NUnit.Engine.Api/ITestAgentProvider.cs new file mode 100644 index 0000000..490d3f6 --- /dev/null +++ b/src/NUnit.Engine.Api/ITestAgentProvider.cs @@ -0,0 +1,53 @@ +// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt + +using System; + +namespace NUnit.Engine.Services +{ + /// + /// An object implementing ITestAgentProvider is able to provide + /// test agents, which satisfy the criteria specified in a TestPackage. + /// The engine loads implementations through /NUnit/Engine/AgentProviders. + /// Capability queries do not acquire execution ownership. An acquired agent + /// remains associated with its provider until ReleaseAgent succeeds. + /// + public interface ITestAgentProvider : ITestAgentInfo + { + /// + /// Returns true if an agent can be found, which is suitable + /// for running the provided test package. + /// + /// A TestPackage + /// True if the provider can supply a compatible agent. + /// Capability queries must not acquire execution ownership. + bool IsAgentAvailable(TestPackage package); + + /// + /// Return an agent, which best matches the criteria defined + /// in a TestPackage. + /// + /// The test package to be run + /// An ITestAgent + /// If the package is invalid. + /// If no compatible agent is available. + ITestAgent GetAgent(TestPackage package); + + /// + /// Releases the test agent back to the supplier, which provided it. + /// + /// An agent previously provided by a call to GetAgent. + /// + /// If agent was never provided by the factory or was previously released. + /// + /// + /// Return the agent through the same provider which acquired it so that + /// ownership bookkeeping remains consistent. A stop request, a closed + /// connection or disposal of a runner is not confirmation of release. + /// If release fails, retain ownership until the provider can reconcile it. + /// The provider defines how it stops its agent. Successful release alone + /// does not prove that external deployment files can be deleted safely; + /// remote providers must confirm execution has stopped before allowing cleanup. + /// + void ReleaseAgent(ITestAgent agent); + } +}