Refactor the temporal.testing.env

N.B. This is a breaking change for the temporal.testing.env namespace.

There are use cases where we need to pass a temporal client in the :ctx, but this was impossible
with the current "all in one" design of temporal.testing.env/create.

Therefore, we split this up into three distinct operations: create/start/get-client.  This
now means that we get a chance to call create/get-client before invoking start, yielding
the opportunity to build the worker :ctx as we require.

Signed-off-by: Greg Haskins <[email protected]>

Author: ghaskins

doc/testing.md

@@ -31,12 +31,16 @@ You can use the provided environment with a Clojure unit testing framework of yo
 
 (deftest my-test
   (testing "Verifies that we can invoke our greeter workflow"
-    (let [{:keys [client] :as env} (e/create {:task-queue task-queue})
-          (c/create-workflow client greeter-workflow {:task-queue task-queue})]
-      (c/start workflow {:name "Bob"})
+    (let [env    (e/create)
+          client (e/get-client env)]
+      (e/start env {:task-queue task-queue})
+      (let [workflow (c/create-workflow client greeter-workflow {:task-queue task-queue})]
+        (c/start workflow {:name "Bob"}))
       (is (= @(c/get-result workflow) "Hi, Bob")))))
 ```
 
-The primary difference between this test and a real-world application is the use of [temporal.testing.env/create](https://cljdoc.org/d/io.github.manetu/temporal-sdk/CURRENT/api/temporal.testing.env#create) function.  This method simultaneously creates an instance of the in-memory Temporal service *and* a client already connected to this environment.
+The primary difference between this test and a real-world application is the use of [temporal.testing.env/create](https://cljdoc.org/d/io.github.manetu/temporal-sdk/CURRENT/api/temporal.testing.env#create) function.  The features in the temporal.testing.env namespace allow you to create an instance of an in-memory Temporal service along with an associated Temporal worker and client connected to this instance.
 
-Typical tests may opt to create the testing environment within a [fixture](https://clojuredocs.org/clojure.test/use-fixtures), but this is left as an exercise to the reader.  The testing environment may be cleanly shutdown with [temporal.testing.env/stop](https://cljdoc.org/d/io.github.manetu/temporal-sdk/CURRENT/api/temporal.testing.env#stop).
+Typical tests may opt to create the testing environment within a [fixture](https://clojuredocs.org/clojure.test/use-fixtures), but this is left as an exercise to the reader.
+
+The testing environment may be cleanly shutdown with [temporal.testing.env/stop](https://cljdoc.org/d/io.github.manetu/temporal-sdk/CURRENT/api/temporal.testing.env#stop).

project.clj

@@ -1,4 +1,4 @@
-(defproject io.github.manetu/temporal-sdk "0.10.5-SNAPSHOT"
+(defproject io.github.manetu/temporal-sdk "0.11.0-SNAPSHOT"
   :description "A Temporal SDK for Clojure"
   :url "https://github.com/manetu/temporal-clojure-sdk"
   :license {:name "Apache License 2.0"

src/temporal/testing/env.clj

@@ -8,25 +8,33 @@
 
 (defn create
   "
-Creates a mock environment and an associated client connection for emulating the combination of a worker and a Temporal
-backend, suitable for unit testing.
+Creates a mock Temporal backend, suitable for unit testing.
+
+A worker may be created with [[start]] and a client may be connected with [[get-client]]
+"
+  []
+  (TestWorkflowEnvironment/newInstance))
+
+(defn start
+  "
+Starts a Temporal worker associated with the mock environment created with [[create]].
 
 Arguments:
 
   - `options`:  See [[temporal.client.worker/worker-options]]
 
 ```clojure
-(let [{:keys [client] :as instance} (create {:task-queue ::my-queue :ctx {:some \"context\"}}]
+(let [env (create)]
+  (start env {:task-queue ::my-queue :ctx {:some \"context\"}})
   ;; create and invoke workflows
-  (stop instance))
+  (stop env))
 ```
 "
-  [{:keys [task-queue] :as options}]
-  (let [env (TestWorkflowEnvironment/newInstance)
-        worker (.newWorker env (u/namify task-queue))]
+  [env {:keys [task-queue] :as options}]
+  (let [worker (.newWorker env (u/namify task-queue))]
     (worker/init worker options)
     (.start env)
-    {:env env :worker worker :client (.getWorkflowClient env)}))
+    :ok))
 
 (defn stop
   "
@@ -37,7 +45,7 @@ see [[synchronized-stop]].
 (stop instance)
 ```
 "
-  [{:keys [^TestWorkflowEnvironment env]}]
+  [^TestWorkflowEnvironment env]
   (.shutdown env))
 
 (defn synchronized-stop
@@ -49,5 +57,10 @@ see [[stop]]
 (synchronized-stop instance)
 ```
 "
-  [{:keys [^TestWorkflowEnvironment env]}]
+  [^TestWorkflowEnvironment env]
   (.close env))
+
+(defn get-client
+  "Returns a client instance associated with the mock environment created by [[create]]"
+  [env]
+  (.getWorkflowClient env))

test/temporal/test/manual_dispatch.clj

@@ -49,8 +49,10 @@
 ;; Fixtures
 ;;-----------------------------------------------------------------------------
 (defn create-service []
-  (let [{:keys [client] :as env} (e/create {:task-queue task-queue
-                                            :dispatch {:workflows [explicitly-registered-workflow]}})] ;; note that we intentionally omit explicitly-skipped-workflow
+  (let [env    (e/create)
+        client (e/get-client env)]
+    (e/start env {:task-queue task-queue
+                  :dispatch {:workflows [explicitly-registered-workflow]}}) ;; note that we intentionally omit explicitly-skipped-workflow
     (swap! state assoc
            :env env
            :client client)))

test/temporal/test/utils.clj

@@ -29,7 +29,9 @@
 ;; Fixtures
 ;;-----------------------------------------------------------------------------
 (defn create-service []
-  (let [{:keys [client] :as env} (e/create {:task-queue task-queue})]
+  (let [env    (e/create)
+        client (e/get-client env)]
+    (e/start env {:task-queue task-queue})
     (swap! state assoc
            :env env
            :client client)))