DOCS : Moved separation of test concerns essay into org file to allow…

… for easier copy over.

docs/src/approach/separation-of-test-concerns.md → docs/src/approach/separation-of-test-concerns.org

@@ -1,11 +1,17 @@
----
-title: Separation of Test Concerns
----
-# Separation of Test Concerns
+* Separation of Test Concerns :wdoc:wpublish:
+:PROPERTIES:
+:directory: hitchstory/docs/src/approach/
+:END:
 
-Separation of Test Concerns is a form of [separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns) where the user story of a test is described declaratively and kept entirely separate from the [turing complete](https://en.m.wikipedia.org/wiki/Turing_completeness) code (the "engine") that executes it.
+** #intro
 
-It mirrors the separation of concerns exhibited by web applications adhering to the [MVC](https://en.m.wikipedia.org/wiki/Model–view–controller) pattern ([MTV](https://docs.djangoproject.com/en/2.1/faq/general/#django-appears-to-be-a-mvc-framework-but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-don-t-use-the-standard-names) in the Django world).With hitchstory, an example of a non-turing complete, declarative user story would look something like this:
+Separation of Test Concerns is a form of [[https://en.wikipedia.org/wiki/Separation_of_concerns][separation of concerns]] where the user story of a test is described declaratively and kept entirely separate from the [[https://en.m.wikipedia.org/wiki/Turing_completeness][turing complete]] code (the "engine") that executes it.
+
+It mirrors the separation of concerns exhibited by web applications adhering to the [[https://en.m.wikipedia.org/wiki/Model–view–controller][MVC]] pattern ([[https://docs.djangoproject.com/en/2.1/faq/general/#django-appears-to-be-a-mvc-framework-but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-don-t-use-the-standard-names][MTV]] in the Django world).
+
+** #
+
+With hitchstory, an example of a non-turing complete, declarative user story would look something like this:
 
 ```yaml
 Logged in as AzureDiamond:
@@ -31,8 +37,7 @@ With corresponding engine code looking like this:
         self.driver.click(name=name)
 ```
 
-
-## xUnit tests : no separation of concerns
+** xUnit tests : no separation of concerns
 
 Unlike with hitchstory, xUnit tests do not have a layer to enforce separation test of concerns.
 
@@ -59,10 +64,7 @@ def test_add_user(browser, web_server, init, dbsession):
 
 This isnt always the case, however, and it is very frequently the case that the intended behavior is difficult to derive from the test even for a skilled developer.
 
-
-
-
-## No separation: less readable
+** No separation: less readable
 
 Not all tests have an easily discernable specification. For example:
 
@@ -74,10 +76,7 @@ Not all tests have an easily discernable specification. For example:
 
 This isnt a problem with the writer of the test - it is an intrinsic problem with xUnit tests. As they grow, they become more unreadable, and since they largely interact with code APIs the relevance to the overall app may be difficult to discern.
 
-
-
-
-## Cucumber / Gherkin: Separation only between high level description and the rest
+** Cucumber / Gherkin: Separation only between high level description and the rest
 
 Cucumber (as well as its derivatives) is another framework that enforces a language layer, but instead of enforcing a separation between specification and execution it is shaped around creating a much less useful separation between high level specifications and the rest.
 
@@ -90,11 +89,8 @@ An example of such a high level scenario (drawn from a representative cucumber t
     And API: I check that POST call status code is 200
 ```
 
-This example exhibits [test concern leakage](../test-concern-leakage).
+This example exhibits [[../test-concern-leakage][test concern leakage]].
 
 This provides a limited window into the intended (or actual) behavior of the API as it is a very high level overview of the API's behavior. Key specification details about this story will still exist in this executable specification but they will be buried in the step code that the above translates to. 
 
 Due to the need to bury key specification details (e.g. the contents of the API call creating the person), the step code will also have to be highly specialized and step code reusability will be inhibited.
-
-
-