+testkit,actorable #248 ActorableTestProbe

resolves #248

Author: ktoso

Docs/actorables.adoc

@@ -302,6 +302,13 @@ swift run GenActors
 The GenActors command by default inspects the `Sources` directory for files and detects top level types conforming to the
 api:Actorable[protocol] protocol. Optionally, you may pass folder paths or file names explicitly.
 
+=== Actorables and Serialization
+
+#TODO: This needs a remake of the serialization story as we want them to automatically "just work".#
+
+Currently no special codegen is enabled for Actorables, so in order to send messages to other processes or nodes,
+you will have to register serializers same as in the behavior style, see: <<serialization>>.
+
 === Actorable.Message and Serialization
 
 `GenActors` also generates an additional file suffixed `+GenCodable.swift` which contains `Codable` conformance for an actorable's `Message` type.
@@ -320,3 +327,34 @@ You still have to *register* the the type with the serialization infrastructure
 
 TIP: We aim to simplify the serialization infrastructure to be able to infer more about what serializer to use for a given type,
      however the current approach remains valid (and most resilient in face of type refactorings).
+
+=== ActorTestKit and ActorableTestProbe
+
+An `ActorTestKit` is offered to simplify the testing of actors and asynchronous code.
+The most important part of the test kit is api:ActorTestProbe[class] (for `ActorRef` / `Behavior` style)
+and api:ActorableTestProbe[class] for actorables.
+
+#TODO: Write full docs for ActorTestKit (and reconsider naming... w discussed but are unsure still ActorTestTools was an option)#
+
+After creating an api:ActorTestKit[class] for an api:ActorSystem[class], one is able to `testKit.spawnActorableTestProbe` a probe for any given api:Actorable[protocol].
+The returned api:ActorableTestProbe[class] contains the "mocked" `.actor` reference as well as various `expectMessage`-style methods, which allow
+the test to block for a time, expecting a message to be send to the underlying test probe (configurable using the optional `within:` parameter).
+
+For example, in order to mock out a reference to such an `GreetMe` actorable:
+
+[source]
+----
+include::{dir_sact_doc_tests}/Actorable/ActorableActorTestKitDocExamples.swift[tag=actorable]
+----
+
+You may spawn a probe for it, and expect that it receives a hello message when passed to another actor:
+
+[source]
+----
+include::{dir_sact_doc_tests}/Actorable/ActorableActorTestKitDocExamples.swift[tag=full_testkit_example]
+----
+<1> Spawn a test probe, abiding to `GreetMe`'s message protocol
+<2> Spawn a real `GreetMeGreeter` actor, and tell it to greet the probe actor
+<3> Expect that the probe gets the expected message, and that it's contents are indeed correct
+
+NOTE: To learn more about all the available expectations on test probes, refer to api:ActorableTestProbe[class] API documentation.

Samples/Sources/XPCActorServiceAPI/GenActors/GreetingsService+GenActor.swift

@@ -2,19 +2,6 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
 
 // tag::xpc_example[]
 import DistributedActors

Samples/Sources/XPCActorServiceAPI/GenActors/GreetingsService+GenCodable.swift

@@ -2,19 +2,6 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
 
 // tag::xpc_example[]
 import DistributedActors

Samples/Sources/XPCActorServiceAPI/GenActors/GreetingsService+XPCProtocolStub.swift

@@ -2,19 +2,6 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
 
 // tag::xpc_example[]
 import DistributedActors

Samples/Sources/XPCActorServiceAPI/GenActors/GreetingsServiceStub+GenActor.swift

@@ -6,19 +6,6 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
 
 // tag::xpc_example[]
 import DistributedActors

Samples/Sources/XPCActorServiceAPI/GenActors/GreetingsServiceStub+GenCodable.swift

@@ -6,19 +6,6 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
 
 // tag::xpc_example[]
 import DistributedActors

Samples/Sources/XPCActorServiceProvider/GenActors/GreetingsServiceImpl+GenActor.swift

@@ -2,19 +2,7 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
+
 
 import DistributedActors
 import XPCActorServiceAPI

Samples/Sources/XPCActorServiceProvider/GenActors/GreetingsServiceImpl+GenCodable.swift

@@ -2,19 +2,7 @@
 // === DO NOT EDIT: Generated by GenActors                     
 // ==== ------------------------------------------------------------------ ====
 
-//===----------------------------------------------------------------------===//
-//
-// This source file is part of the Swift Distributed Actors open source project
-//
-// Copyright (c) 2019 Apple Inc. and the Swift Distributed Actors project authors
-// Licensed under Apache License v2.0
-//
-// See LICENSE.txt for license information
-// See CONTRIBUTORS.md for the list of Swift Distributed Actors project authors
-//
-// SPDX-License-Identifier: Apache-2.0
-//
-//===----------------------------------------------------------------------===//
+
 
 import DistributedActors
 import XPCActorServiceAPI

Sources/DistributedActorsTestKit/ActorTestKit.swift

@@ -63,9 +63,9 @@ public struct ActorTestKitSettings {
 // ==== ----------------------------------------------------------------------------------------------------------------
 // MARK: Test Probes
 
-public extension ActorTestKit {
+extension ActorTestKit {
     /// Spawn an `ActorTestProbe` which offers various assertion methods for actor messaging interactions.
-    func spawnTestProbe<M>(_ naming: ActorNaming? = nil, expecting type: M.Type = M.self, file: StaticString = #file, line: UInt = #line) -> ActorTestProbe<M> {
+    public func spawnTestProbe<M>(_ naming: ActorNaming? = nil, expecting type: M.Type = M.self, file: StaticString = #file, line: UInt = #line) -> ActorTestProbe<M> {
         self.spawnProbesLock.lock()
         defer { self.spawnProbesLock.unlock() }
         // we want to use our own sequence number for the naming here, so we make it here rather than let the
@@ -88,6 +88,43 @@ public extension ActorTestKit {
             return try system.spawn(.init(unchecked: .unique(name)), props: testProbeProps, probeBehavior)
         }, settings: self.settings)
     }
+
+    /// Spawn `ActorableTestProbe` which offers various assertions for actor messaging interactions.
+    public func spawnActorableTestProbe<A: Actorable>(_ naming: ActorNaming? = nil, of actorable: A.Type = A.self, file: StaticString = #file, line: UInt = #line)
+        -> ActorableTestProbe<A> {
+        self.spawnProbesLock.lock()
+        defer { self.spawnProbesLock.unlock() }
+        // we want to use our own sequence number for the naming here, so we make it here rather than let the
+        // system use its own sequence number -- which should only be in use for the user actors.
+        let name: String
+        if let naming = naming {
+            name = naming.makeName(&self._namingContext)
+        } else {
+            name = ActorTestProbe<A.Message>.naming.makeName(&self._namingContext)
+        }
+
+        return ActorableTestProbe(spawn: { probeBehavior in
+
+            // TODO: allow configuring dispatcher for the probe or always use the calling thread one
+            var testProbeProps = Props()
+            #if SACT_PROBE_CALLING_THREAD
+            testProbeProps.dispatcher = .callingThread
+            #endif
+
+            return try system.spawn(.init(unchecked: .unique(name)), props: testProbeProps, probeBehavior)
+        }, settings: self.settings)
+    }
+}
+
+/// A test probe pretends to be the `Actorable` and allows expecting messages be sent to it.
+///
+/// - SeeAlso: `ActorTestProbe` which is the equivalent API for `ActorRef`s.
+public final class ActorableTestProbe<A: Actorable>: ActorTestProbe<A.Message> {
+    /// `Actor` reference to the underlying test probe actor.
+    /// All message sends invoked on this Actor will result in messages in the probe available to be `expect`-ed.
+    public var actor: Actor<A> {
+        return Actor(ref: self.ref)
+    }
 }
 
 // ==== ----------------------------------------------------------------------------------------------------------------

Sources/DistributedActorsTestKit/TestProbes.swift

@@ -29,24 +29,32 @@ extension ActorTestProbeCommand: NoSerializationVerification {}
 
 /// A special actor that can be used in place of real actors, yet in addition exposes useful assertion methods
 /// which make testing asynchronous actor interactions simpler.
-public final class ActorTestProbe<Message> {
+///
+/// - SeeAlso: `ActorableTestProbe` which is the equivalent API for `Actorable`s.
+public class ActorTestProbe<Message> {
+    /// Name of the test probe (and underlying actor).
     public let name: String
+
+    /// Naming strategy for anonymous test probes.
+    /// By default test probes are named as `$testProbe-###`.
     public static var naming: ActorNaming {
         // has to be computed property since: static stored properties are not supported in generic types
-        return ActorNaming(unchecked: .prefixed(prefix: "$testProbe", suffixScheme: .sequentialNumeric))
+        ActorNaming(unchecked: .prefixed(prefix: "$testProbe", suffixScheme: .sequentialNumeric))
     }
 
     typealias ProbeCommands = ActorTestProbeCommand<Message>
     internal let internalRef: ActorRef<ProbeCommands>
     internal let exposedRef: ActorRef<Message>
 
+    /// The reference to the underlying "mock" actor.
+    /// Sending messages to this reference allows the probe to inspect them using the `expect...` family of functions.
     public var ref: ActorRef<Message> {
-        return self.exposedRef
+        self.exposedRef
     }
 
     private let settings: ActorTestKitSettings
     private var expectationTimeout: TimeAmount {
-        return self.settings.expectationTimeout
+        self.settings.expectationTimeout
     }
 
     /// Blocking linked queue, available to run assertions on