Add new interfaces and enable use of launchers internally

Author: CharliePoole

package-tests.cake

@@ -57,7 +57,7 @@ StandardRunnerTests.Add(new PackageTest(1, "Net462Test")
 AddToBothLists(new PackageTest(1, "Net80Test")
 {
     Description = "Run mock-assembly.dll under .NET 8.0",
-    Arguments = "testdata/net8.0/mock-assembly.dll",
+    Arguments = "testdata/net8.0/mock-assembly.dll --trace:Debug",
     ExpectedResult = new MockAssemblyExpectedResult("netcore-8.0")
 });
 

src/NUnitCommon/nunit.extensibility.tests/ExtensionManagerTests.cs

@@ -18,6 +18,7 @@ public class ExtensionManagerTests
 #pragma warning disable 414
         private static readonly string[] KnownExtensionPointPaths =
         {
+            "/NUnit/Engine/TypeExtensions/IAgentLauncher",
             "/NUnit/Engine/TypeExtensions/IDriverFactory",
             "/NUnit/Engine/TypeExtensions/IProjectLoader",
             "/NUnit/Engine/TypeExtensions/IResultWriter",
@@ -28,6 +29,7 @@ public class ExtensionManagerTests
 
         private static readonly Type[] KnownExtensionPointTypes =
         {
+            typeof(IAgentLauncher),
             typeof(IDriverFactory),
             typeof(IProjectLoader),
             typeof(IResultWriter),
@@ -36,8 +38,9 @@ public class ExtensionManagerTests
             typeof(IFrameworkDriver)
         };
 
-        private static readonly int[] KnownExtensionPointCounts = { 1, 1, 1, 2, 1, 0 };
+        private static readonly int[] KnownExtensionPointCounts = { 1, 1, 1, 1, 2, 1, 0 };
 
+        private const string FAKE_AGENT_LAUNCHER_EXTENSION = "NUnit.Engine.Fakes.FakeAgentLauncherExtension";
         private const string FAKE_FRAMEWORK_DRIVER_EXTENSION = "NUnit.Engine.Fakes.FakeFrameworkDriverExtension";
         private const string FAKE_PROJECT_LOADER_EXTENSION = "NUnit.Engine.Fakes.FakeProjectLoaderExtension";
         private const string FAKE_RESULT_WRITER_EXTENSION = "NUnit.Engine.Fakes.FakeResultWriterExtension";
@@ -48,6 +51,7 @@ public class ExtensionManagerTests
 
         private readonly string[] KnownExtensions =
         {
+            FAKE_AGENT_LAUNCHER_EXTENSION,
             FAKE_FRAMEWORK_DRIVER_EXTENSION,
             FAKE_PROJECT_LOADER_EXTENSION,
             FAKE_RESULT_WRITER_EXTENSION,

src/NUnitEngine/agents/nunit-agent-net80/nunit-agent-net80.csproj

@@ -8,7 +8,6 @@
     <ApplicationManifest>app.manifest</ApplicationManifest>
     <ApplicationIcon>..\..\..\..\nunit.ico</ApplicationIcon>
     <GenerateSupportedRuntime>false</GenerateSupportedRuntime>
-    <EnableUnsafeBinaryFormatterSerialization>true</EnableUnsafeBinaryFormatterSerialization>
   </PropertyGroup>
 
   <PropertyGroup>

src/NUnitEngine/nunit.engine.api/EnginePackageSettings.cs

@@ -88,6 +88,16 @@ public static class EnginePackageSettings
         /// </summary>
         public const string TargetRuntimeFramework = "TargetRuntimeFramework";
 
+        /// <summary>
+        /// Indicates the name of the agent requested by the user.
+        /// </summary>
+        public const string RequestedAgentName = "RequestedAgentName";
+
+        /// <summary>
+        /// Indicates the name of the agent that was actually used.
+        /// </summary>
+        public const string SelectedAgentName = "SelectedAgentName";
+
         /// <summary>
         /// Bool flag indicating that the test should be run in a 32-bit process
         /// on a 64-bit system. By default, NUNit runs in a 64-bit process on

src/NUnitEngine/nunit.engine.api/Extensibility/IAgentLauncher.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt
+
+using System;
+using System.Diagnostics;
+using NUnit.Extensibility;
+
+namespace NUnit.Engine.Extensibility
+{
+    /// <summary>
+    /// Interface implemented by an agent launcher, which is able to examine
+    /// a test package, evaluate whether it can create an agent for it and
+    /// create the agent itself on request.
+    /// </summary>
+    [TypeExtensionPoint(
+        Description = "Launches an Agent Process for supported target runtimes")]
+    public interface IAgentLauncher
+    {
+        /// <summary>
+        /// Gets a TestAgentInfo describing this agent
+        /// </summary>
+        TestAgentInfo AgentInfo { get; }
+
+        /// <summary>
+        /// Returns true if the launcher can create an agent for the supplied package, otherwise false.
+        /// </summary>
+        /// <param name="package"></param>
+        /// <returns></returns>
+        bool CanCreateAgent(TestPackage package);
+
+        /// <summary>
+        /// Returns an agent capable of running the specified package.
+        /// </summary>
+        /// <param name="agentId"></param>
+        /// <param name="agencyUrl"></param>
+        /// <param name="package"></param>
+        /// <returns></returns>
+        Process CreateAgent(Guid agentId, string agencyUrl, TestPackage package);
+    }
+}

src/NUnitEngine/nunit.engine.api/ITestAgentInfo.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt
+
+using System.Collections.Generic;
+
+namespace NUnit.Engine.Services
+{
+    /// <summary>
+    /// Objects implementing ITestAgentInfo by classes that can return information about
+    /// available agents. The interface is used by runners in order to provide information
+    /// to the user or to allow selecting agents.
+    /// </summary>
+    public interface ITestAgentInfo
+    {
+        /// <summary>
+        /// Gets a list containing <see cref="TestAgentInfo"/> for all available agents.
+        /// </summary>
+        IList<TestAgentInfo> GetAvailableAgents();
+
+        /// <summary>
+        /// Gets a list containing <see cref="TestAgentInfo"/> for any available agents,
+        /// which are able to handle the specified package.
+        /// </summary>
+        /// <param name="package">A TestPackage</param>
+        /// <returns>
+        /// A list of suitable agents for running the package or an empty
+        /// list if no agent is available for the package.
+        /// </returns>
+        IList<TestAgentInfo> GetAgentsForPackage(TestPackage package);
+    }
+}

src/NUnitEngine/nunit.engine.api/TestAgentInfo.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt
+
+using System.Runtime.Versioning;
+
+namespace NUnit.Engine
+{
+    /// <summary>
+    /// The TestAgentInfo struct provides information about an
+    /// available agent for use by a runner.
+    /// </summary>
+    public struct TestAgentInfo
+    {
+        /// <summary>
+        /// The name of this agent
+        /// </summary>
+        public string AgentName;
+
+        /// <summary>
+        /// The agent type: InProcess, LocalProcess or RemoteProcess
+        /// </summary>
+        public TestAgentType AgentType;
+
+        /// <summary>
+        /// The target runtime used by this agent
+        /// </summary>
+        public FrameworkName TargetRuntime;
+
+        /// <summary>
+        /// Construct a TestAgent Info
+        /// </summary>
+        /// <param name="agentName">The agent name</param>
+        /// <param name="agentType">The AgentType</param>
+        /// <param name="targetRuntime">The target runtime</param>
+        public TestAgentInfo(string agentName, TestAgentType agentType, FrameworkName targetRuntime)
+        {
+            AgentName = agentName;
+            AgentType = agentType;
+            TargetRuntime = targetRuntime;
+        }
+    }
+}

src/NUnitEngine/nunit.engine.api/TestAgentType.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Charlie Poole, Rob Prouse and Contributors. MIT License - see LICENSE.txt
+
+namespace NUnit.Engine
+{
+    /// <summary>
+    /// <para>TestAgentType is an enumeration of the types
+    /// of agents, which may be available. Currently, three
+    /// types are defined, of which one is implemented.</para>
+    /// </summary>
+    /// <remarks>
+    /// A user requests a particular agent type by including a
+    /// "TestAgentType" setting in the test package. The setting
+    /// is optional and the runner will select an agent of any
+    /// type available if it isn't specified.
+    /// </remarks>
+    public enum TestAgentType
+    {
+        /// <summary>
+        /// Any agent type is acceptable. This is the default value,
+        /// so it never needs to be specified by the user. This
+        /// setting is not valid in the TestAgentInfo struct, since
+        /// each agent must be of some particular type.
+        /// </summary>
+        Any = 0,
+
+        /// <summary>
+        /// An in-process agent. This type is not directly supported
+        /// by the engine but may be provided by an extension.
+        /// </summary>
+        InProcess = 1,
+
+        /// <summary>
+        /// An agent running as a separate local process.
+        /// A supplier for this type is built into the engine.
+        /// </summary>
+        LocalProcess = 2,
+
+        /// <summary>
+        /// An agent running on a server, that is a separate
+        /// machine, which may be specified in the request or
+        /// left up to the agent supplier to determine. A supplier
+        /// for this type may be developed in the future.
+        /// </summary>
+        RemoteProcess = 3
+    }
+}

src/NUnitEngine/nunit.engine.tests/Services/AgentStoreTests.DummyTestAgent.cs

@@ -32,7 +32,7 @@ public static void IdCannotBeReused()
             database.Register(DummyAgent);
             Assert.That(() => database.AddAgent(DummyAgentId, DummyProcess), Throws.ArgumentException.With.Property("ParamName").EqualTo("agentId"));
 
-            database.MarkTerminated(DummyAgentId);
+            database.MarkProcessTerminated(DummyProcess);
             Assert.That(() => database.AddAgent(DummyAgentId, DummyProcess), Throws.ArgumentException.With.Property("ParamName").EqualTo("agentId"));
         }
 
@@ -60,7 +60,7 @@ public static void AgentMustNotRegisterAfterTerminating()
             var database = new AgentStore();
 
             database.AddAgent(DummyAgentId, DummyProcess);
-            database.MarkTerminated(DummyAgentId);
+            database.MarkProcessTerminated(DummyProcess);
             Assert.That(() => database.Register(DummyAgent), Throws.ArgumentException.With.Property("ParamName").EqualTo("agent"));
         }
 
@@ -69,7 +69,8 @@ public static void AgentMustBeStartedBeforeTerminating()
         {
             var database = new AgentStore();
 
-            Assert.That(() => database.MarkTerminated(DummyAgentId), Throws.ArgumentException.With.Property("ParamName").EqualTo("agentId"));
+            Assert.That(() => database.MarkProcessTerminated(DummyProcess),
+                Throws.Exception.TypeOf<NUnitEngineException>().With.Message.EqualTo("Process terminated without registering an agent."));
         }
 
         [Test]
@@ -107,7 +108,7 @@ public static void AgentIsNotReadyWhenTerminated()
 
             database.AddAgent(DummyAgentId, DummyProcess);
             database.Register(DummyAgent);
-            database.MarkTerminated(DummyAgentId);
+            database.MarkProcessTerminated(DummyProcess);
             Assert.That(database.IsReady(DummyAgentId, out _), Is.False);
         }
 
@@ -147,7 +148,7 @@ public static void AgentIsNotRunningWhenTerminated()
 
             database.AddAgent(DummyAgentId, DummyProcess);
             database.Register(DummyAgent);
-            database.MarkTerminated(DummyAgentId);
+            database.MarkProcessTerminated(DummyProcess);
             Assert.That(database.IsAgentProcessActive(DummyAgentId, out _), Is.False);
         }
 
@@ -169,11 +170,13 @@ public static void ConcurrentOperationsDoNotCorruptState()
                     Assert.That(database.IsAgentProcessActive(id, out _), Is.True);
                     Assert.That(database.IsReady(id, out _), Is.False);
 
+                    // Pretend that the agent process started and  registered
                     database.Register(new DummyTestAgent(id));
                     Assert.That(database.IsAgentProcessActive(id, out _), Is.True);
                     Assert.That(database.IsReady(id, out _), Is.True);
 
-                    database.MarkTerminated(id);
+                    //database.MarkProcessTerminated(DummyProcess);
+                    database.MarkAgentTerminated(id);
                     Assert.That(database.IsAgentProcessActive(id, out _), Is.False);
                     Assert.That(database.IsReady(id, out _), Is.False);
                 }
@@ -210,6 +213,35 @@ private static void RunActionConcurrently(Action action, int threadCount)
             if (exceptions.Count != 0)
                 throw exceptions[0];
         }
+
+        #region Nested DummyTestAgent Class
+
+        private sealed class DummyTestAgent : ITestAgent
+        {
+            public DummyTestAgent(Guid id)
+            {
+                Id = id;
+            }
+
+            public Guid Id { get; }
+
+            public ITestEngineRunner CreateRunner(TestPackage package)
+            {
+                throw new NotImplementedException();
+            }
+
+            public bool Start()
+            {
+                throw new NotImplementedException();
+            }
+
+            public void Stop()
+            {
+                throw new NotImplementedException();
+            }
+        }
+
+        #endregion
     }
 }
 #endif

src/NUnitEngine/nunit.engine.tests/Services/AgentStoreTests.cs

@@ -261,9 +261,6 @@ private void CreateAgentAndRunnerIfNeeded()
                              TestPackage.GetSetting(EnginePackageSettings.PauseBeforeRun, false);
 
                 _agent = _agency.GetAgent(TestPackage);
-
-                if (_agent is null)
-                    throw new NUnitEngineException("Unable to acquire remote process agent");
             }
 
             if (_remoteRunner is null)