test literate programming scripts

Author: jkone27

.devcontainer/devcontainer.json

@@ -0,0 +1,7 @@
+{
+  "tasks": {
+    "test": "dotnet tool restore && dotnet fsdocs build",
+    "build": "dotnet tool restore && dotnet build",
+    "launch": "dotnet tool restore && dotnet build && dotnet fsdocs watch"
+  }
+}

docs/bdd_extensions.fsx

@@ -0,0 +1,73 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
+## BDD (gherkin) Extensions 🥒
+
+You can use some BDD extension to perform [Gherkin-like setups and assertions](https://cucumber.io/docs/gherkin/reference/)
+
+they are all async `task` computations so they can be simply chained together:
+
+* `SCENARIO`: takes a `TestClient<TStartup>` as input and needs a name for your test scenario
+* `SETUP`: takes a scenario as input and can be used to configure the "test environmenttest": factory and the API client, additionally takes a separate API client configuration
+* `GIVEN`: takes a "test environment" or another "given" and returns a "given" step
+* `WHEN`: takes a "given" or another "when" step, and returns a a "when" step
+* `THEN`: takes a "when" step and asserts on it, returns the same "when" step as result to continue asserts
+* `END`: disposes the "test environment" and concludes the task computation
+
+```fsharp
+// open ...
+open ApiStub.FSharp.BDD
+open HttpResponseMessageExtensions
+
+module BDDTests =
+
+    let testce = new TestClient<Startup>()
+
+    [<Fact>]
+    let ``when i call /hello i get 'world' back with 200 ok`` () =
+            
+            let mutable expected = "_"
+            let stubData = { Ok = "undefined" }
+
+            // ARRANGE step is divided in CE (arrange client stubs)
+            // SETUP: additional factory or service or client configuration
+            // and GIVEN the actual arrange for the test 3As.
+                
+            // setup your test as usual here, test_ce is an instance of TestClient<TStartup>()
+            test_ce {
+                POSTJ "/another/anotherApi" {| Test = "NOT_USED_VAL" |}
+                GET_ASYNC "/externalApi" (fun r _ -> task { 
+                    return { stubData with Ok = expected } |> R_JSON 
+                })
+            }
+            |> SCENARIO "when i call /Hello i get 'world' back with 200 ok"
+            |> SETUP (fun s -> task {
+            
+                let test = s.TestClient
+                
+                // any additiona services or factory configuration before this point
+                let f = test.GetFactory() 
+                
+                return {
+                    Client = f.CreateClient()
+                    Factory = f
+                    Scenario = s
+                    FeatureStubData = stubData
+                }
+            }) (fun c -> c) // configure test client here if needed
+            |> GIVEN (fun g -> //ArrangeData
+                expected <- "world"
+                expected |> Task.FromResult
+            )
+            |> WHEN (fun g -> task { //ACT and AssertData
+                let! (r : HttpResponseMessage) = g.Environment.Client.GetAsync("/Hello")
+                return! r.Content.ReadFromJsonAsync<Hello>()
+
+            })
+            |> THEN (fun w -> // ASSERT
+                Assert.Equal(w.Given.ArrangeData, w.AssertData.Ok) 
+            )
+            |> END
+
+```

docs/configuration_helpers.fsx

@@ -0,0 +1,87 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
+## Configuration helpers 🪈
+
+* `WITH_SERVICES`: to override your ConfigureServices for tests
+* `WITH_TEST_SERVICES`: to override your specific test services (a bit redundant in some cases, depending on the need)
+
+### Example
+
+Here is an example of how to use the configuration helpers:
+
+```fsharp
+open ApiStub.FSharp.CE
+open ApiStub.FSharp.BuilderExtensions
+open ApiStub.FSharp.HttpResponseHelpers
+open Xunit
+
+type ISomeSingleton =
+    interface
+    end
+
+type SomeSingleton(name: string) =
+    class
+        interface ISomeSingleton
+    end
+
+module Tests =
+
+    let test = new TestClient<Startup>()
+
+    [<Fact>]
+    let ``WITH_SERVICES registers correctly`` () =
+        task {
+
+            let testApp =
+                test {
+                    GETJ "hello" {| ResponseCode = 1001 |}
+
+                    WITH_SERVICES(fun (s: IServiceCollection) ->
+                        s.AddSingleton<ISomeSingleton>(new SomeSingleton("John")))
+                }
+
+            let fac = testApp.GetFactory()
+
+            let singleton = fac.Services.GetRequiredService<ISomeSingleton>()
+
+            Assert.NotNull(singleton)
+
+            let client = fac.Services.GetRequiredService<HttpClient>()
+
+            let! resp = client.GetFromJsonAsync<{| ResponseCode: int |}>("hello")
+
+            Assert.Equal(1001, resp.ResponseCode)
+        }
+
+    [<Fact>]
+    let ``WITH_TEST_SERVICES registers correctly`` () =
+        task {
+
+            let singletonMock = { new ISomeSingleton }
+
+            let testApp =
+                test {
+                    GETJ "hello" {| ResponseCode = 1001 |}
+
+                    WITH_SERVICES(fun (s: IServiceCollection) ->
+                        s.AddSingleton<ISomeSingleton>(new SomeSingleton("John")))
+
+                    WITH_TEST_SERVICES(fun s -> s.AddSingleton(singletonMock))
+                }
+
+            let fac = testApp.GetFactory()
+
+            let singleton = fac.Services.GetRequiredService<ISomeSingleton>()
+
+            Assert.NotNull(singleton)
+            Assert.Same(singletonMock, singleton)
+
+            let client = fac.Services.GetRequiredService<HttpClient>()
+
+            let! resp = client.GetFromJsonAsync<{| ResponseCode: int |}>("hello")
+
+            Assert.Equal(1001, resp.ResponseCode)
+        }
+```

docs/features.fsx

@@ -0,0 +1,47 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
+## Features 👨🏻‍🔬
+
+* **HTTP client mock DSL**:
+    * supports main HTTP verbs
+    * support for JSON payload for automatic object serialization
+* **BDD spec dsl extension** (behaviour driven development)
+    * to express tests in gherkin GIVEN, WHEN, THEN format if you want to
+* EXTRAS
+    * utilities for test setup and more...
+
+### Example
+
+Here is an example of how to use the features of this library:
+
+```fsharp
+open ApiStub.FSharp.CE
+open ApiStub.FSharp.BuilderExtensions
+open ApiStub.FSharp.HttpResponseHelpers
+open Xunit
+
+module Tests =
+
+    // build your aspnetcore integration testing CE
+    let test = new TestClient<Startup>()
+
+    [<Fact>]
+    let ``Calls Hello and returns OK`` () =
+
+        task {
+
+            let testApp =
+                test { 
+                    GETJ "/externalApi" {| Ok = "yeah" |}
+                    POSTJ "/anotherApi" {| Whatever = "yeah" |}
+                }
+
+            use client = testApp.GetFactory().CreateClient()
+
+            let! r = client.GetAsync("/Hello")
+
+            r.EnsureSuccessStatusCode()
+        } 
+```

docs/http_methods.fsx

@@ -0,0 +1,51 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
+## HTTP Methods 🚕
+
+Available HTTP methods in the test DSL to "mock" HTTP client responses are the following:
+
+### Basic
+
+* `GET`, `PUT`, `POST`, `DELETE` - for accessing request, route parameters and sending back HttpResponseMessage (e.g. using R_JSON or other constructors)
+
+```fsharp
+    // example of control on request and route value dictionary
+    PUT "/externalApi" (fun r rvd -> 
+        // read request properties or route, but not content...
+        // unless you are willing to wait the task explicitly as result
+        {| Success = true |} |> R_JSON 
+    )
+```
+
+### JSON 📒
+
+* `GETJ`, `PUTJ`, `POSTJ`, `DELETEJ` - for objects converted to JSON content
+
+```fsharp
+GETJ "/yetAnotherOne" {| Success = true |}
+```
+
+### ASYNC Overloads (task) ⚡️
+
+* `GET_ASYNC`, `PUT_ASYNC`, `POST_ASYNC`, `DELETE_ASYNC` - for handling asynchronous requests inside a task computation expression (async/await) and mock dynamically
+
+```fsharp
+// example of control on request and route value dictionary
+    // asynchronously
+    POST_ASYNC "/externalApi" (fun r rvd -> 
+        task {
+            // read request content and meddle here...
+            return {| Success = true |} |> R_JSON 
+        }
+    )
+```
+
+### HTTP response helpers 👨🏽‍🔧
+
+Available HTTP content constructors are: 
+
+* `R_TEXT`: returns plain text
+* `R_JSON`: returns JSON
+* `R_ERROR`: returns an HTTP error

docs/index.md docs/index.fsxdocs/index.md renamed to docs/index.fsx

@@ -1,3 +1,7 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
 # ApiStub.FSharp
 
 <img width="331" alt="Screenshot 2024-12-16 at 13 01 33" src="https://github.com/user-attachments/assets/5095d6cb-63bb-4644-836f-99b5355870fe" />

docs/mechanics.fsx

@@ -0,0 +1,45 @@
+(*** hide ***)
+#r "nuget: FSharp.Formatting, 11.3.0"
+
+(**
+## Mechanics
+
+This library makes use of [F# computation expressions](https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions) to hide some complexity of `WebApplicationFactory` and provide the user with a *domain specific language* (DSL) for integration tests in aspnetcore apps.
+The best way to understand how it all works is checking the [code](https://github.com/jkone27/fsharp-integration-tests/blob/249c3244cd7e20e2168b82a49b6e7e14f2ad1004/ApiStub.FSharp/CE.fs#L176) and this member CE method `GetFactory()` in scope.
+
+If you have ideas for improvements feel free to open an issue/discussion! 
+I do this on my own time, so support is limited but contributions/PRs are welcome 🙏 
+
+### Example
+
+Here is an example of how to use F# computation expressions with this library:
+
+```fsharp
+open ApiStub.FSharp.CE
+open ApiStub.FSharp.BuilderExtensions
+open ApiStub.FSharp.HttpResponseHelpers
+open Xunit
+
+module Tests =
+
+    // build your aspnetcore integration testing CE
+    let test = new TestClient<Startup>()
+
+    [<Fact>]
+    let ``Calls Hello and returns OK`` () =
+
+        task {
+
+            let testApp =
+                test { 
+                    GETJ "/externalApi" {| Ok = "yeah" |}
+                    POSTJ "/anotherApi" {| Whatever = "yeah" |}
+                }
+
+            use client = testApp.GetFactory().CreateClient()
+
+            let! r = client.GetAsync("/Hello")
+
+            r.EnsureSuccessStatusCode()
+        } 
+```