add docs on BPMN unit tests

docs/how_to/bpmn_unit_tests.md

@@ -0,0 +1,48 @@
+# BPMN Unit Tests
+
+Software Engineers test their code.
+With this feature, BPMN authors can test their creations, too.
+These tests can provide you with faster feedback than you would get by simply running your process model, and they allow you to mock out form input and service task connections as well as provide specific input to exercise different branches of your process model.
+BPMN unit tests are designed to give you greater confidence that your process models will work as designed when they are run in the wild, both the first time they are used by real users and also after you make changes to them.
+
+## Creating BPMN Unit Tests
+
+First, create a process model that you want to test.
+Navigate to the process model and add a JSON file based on the name of one of the BPMN files.
+For example, if you have a process model that includes a file called `awesome_script_task.bpmn`, your test JSON file would be called `test_awesome_script_task.json`.
+If you have multiple BPMN files you want to test, you can have multiple test JSON files.
+The BPMN files you test do not have to be marked as the primary file for the process model in question.
+The structure of your json should be as follows:
+
+    {
+      "test_case_1": {
+        "tasks": {
+          "ServiceTaskProcess:service_task_one": {
+            "data": [{ "the_result": "result_from_service" }]
+          }
+        },
+        "expected_output_json": { "the_result": "result_from_service" }
+      }
+    }
+
+The top-level keys should be names of unit tests.
+In this example, the unit test is named "test_case_1."
+Under that, you can specify "tasks" and "expected_output_json."
+
+Under "tasks," each key is the BPMN id of a specific task.
+If you are testing a file that uses Call Activities and therefore calls other processes, there can be conflicting BPMN ids.
+In this case, you can specify the unique activity by prepending the Process id (in the above example, that is "ServiceTaskProcess").
+For simple processes, "service_task_one" (for example) would be sufficient as the BPMN id.
+For User Tasks, the "data" (under a specific task) represents the data that will be entered by the user in the form.
+For Service Tasks, the data represents the data that will be returned by the service.
+Note that all User Tasks and Service Tasks must have their BPMN ids mentioned in the JSON file (with mock task data as desired), since otherwise we won't know what to do when the flow arrives at these types of tasks.
+
+The "expected_output_json" represents the state of the task data that you expect when the process completes.
+When the test is run, if the actual task data differs from this expectation, the test will fail.
+The test will also fail if the process never completes or if an error occurs.
+
+## Running BPMN Unit Tests
+
+Go to a process model and either click “Run Unit Tests” to run all tests for the process model or click on the “play icon” next to a "test_something.json" file.
+Then you will get a green check mark or a red x.
+You can click on these colored icons to get more details about the passing or failing test.

docs/index.md

@@ -1,17 +1,16 @@
-Welcome to SpiffWorkflow's documentation!
-=======================================
+# Welcome to SpiffWorkflow's documentation
 
 ```{toctree}
 :maxdepth: 2
 :caption: Contents
 quick_start/quick_start.md
 documentation/documentation.md
+how_to/bpmn_unit_tests.md
 ```
 
 This is great!
 
-Indices and tables
-==================
+## Indices and tables
 
 * [](genindex)
 * [](modindex)

docs/quick_start/quick_start.md

@@ -307,4 +307,4 @@ Ensure that all required details have been included such as Process name, Proces
 
 By following these steps, you can request the special permissions needed to carry out your tasks effectively.
 
-Changes added by Usama
+Changes added by Usama