feat: testing handlers in isolation (#606)

* feat: testing handlers in isolation

* docs: fix example

Author: sukovanej

.changeset/witty-roses-begin.md

@@ -0,0 +1,34 @@
+---
+"effect-http-node": patch
+---
+
+Add `NodeTesting.handler`. It accepts a `Handler.Handler<A, E, R>` and produces an instance
+of `HttpClient.HttpClient.Default`. It start the server with the handler in a background
+and the produced client has base URL pointing to the server. It behaves exactly like the
+`NodeTesting.makeRaw`, but it works with handlers instead of `HttpApp.HttpApp` instances.
+
+It provides a convenient way to test handlers in isolation.
+
+```ts
+import { HttpClientRequest } from "@effect/platform"
+import { Schema } from "@effect/schema"
+import { expect, it } from "@effect/vitest"
+import { Effect } from "effect"
+import { Api, Handler } from "effect-http"
+import { NodeTesting } from "effect-http-node"
+
+const myEndpoint = Api.get("myEndpoint", "/my-endpoint").pipe(
+  Api.setResponseBody(Schema.Struct({ hello: Schema.String }))
+)
+
+const myHandler = Handler.make(myEndpoint, () => Effect.succeed({ hello: "world" }))
+
+it.scoped("myHandler", () =>
+  Effect.gen(function*() {
+    const client = yield* NodeTesting.handler(myHandler)
+    const response = yield* client(HttpClientRequest.get("/my-endpoint"))
+
+    expect(response.status).toEqual(200)
+    expect(yield* response.json).toEqual({ hello: "world" })
+  }))
+```

docs/_config.yml

@@ -2,4 +2,4 @@ remote_theme: mikearnaldi/just-the-docs
 search_enabled: true
 aux_links:
   "GitHub":
-    - "//github.com/effect-ts/effect"
+    - "//github.com/sukovanej/effect-http"

packages/effect-http-node/docgen.json

@@ -2,5 +2,22 @@
   "$schema": "node_modules/@effect/docgen/schema.json",
   "exclude": [
     "src/internal/**/*.ts"
-  ]
+  ],
+  "examplesCompilerOptions": {
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "module": "ES2022",
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "paths": {
+      "effect-http": ["../../../effect-http/src/index.js"],
+      "effect-http/*": ["../../../effect-http/src/*.js"],
+      "effect-http-security": ["../../../effect-http-security/src/index.js"],
+      "effect-http-security/*": ["../../../effect-http-security/src/*.js"],
+      "effect-http-error": ["../../../effect-http-error/src/index.js"],
+      "effect-http-error/*": ["../../../effect-http-error/src/*.js"]
+    }
+  }
 }

packages/effect-http-node/src/NodeTesting.ts

@@ -3,21 +3,22 @@
  *
  * @since 1.0.0
  */
-import type * as Effect from "effect/Effect"
-import type * as Scope from "effect/Scope"
-
 import type * as NodeContext from "@effect/platform-node/NodeContext"
 import type * as Etag from "@effect/platform/Etag"
 import type * as HttpApp from "@effect/platform/HttpApp"
 import type * as HttpClient from "@effect/platform/HttpClient"
-import type * as HttpClientError from "@effect/platform/HttpClientError"
-import type * as HttpClientResponse from "@effect/platform/HttpClientResponse"
 import type * as HttpPlatform from "@effect/platform/HttpPlatform"
 import type * as HttpServer from "@effect/platform/HttpServer"
 import type * as HttpServerRequest from "@effect/platform/HttpServerRequest"
+import type * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+
 import type * as Api from "effect-http/Api"
+import type * as ApiEndpoint from "effect-http/ApiEndpoint"
 import type * as Client from "effect-http/Client"
+import type * as Handler from "effect-http/Handler"
 import type * as SwaggerRouter from "effect-http/SwaggerRouter"
+
 import * as internal from "./internal/testing.js"
 
 /**
@@ -56,11 +57,7 @@ export const make: <R, E, A extends Api.Api.Any>(
 export const makeRaw: <R, E>(
   app: HttpApp.Default<E, R>
 ) => Effect.Effect<
-  HttpClient.HttpClient<
-    HttpClientResponse.HttpClientResponse,
-    HttpClientError.HttpClientError,
-    Scope.Scope
-  >,
+  HttpClient.HttpClient.Default,
   never,
   | Scope.Scope
   | Exclude<
@@ -74,3 +71,45 @@ export const makeRaw: <R, E>(
     NodeContext.NodeContext
   >
 > = internal.makeRaw
+
+/**
+ * Testing of `Handler.Handler<A, E, R>`.
+ *
+ * @example
+ * import { HttpClientRequest } from "@effect/platform"
+ * import { Schema } from "@effect/schema"
+ * import { Effect } from "effect"
+ * import { Api, Handler } from "effect-http"
+ * import { NodeTesting } from "effect-http-node"
+ *
+ * const myEndpoint = Api.get("myEndpoint", "/my-endpoint").pipe(
+ *   Api.setResponseBody(Schema.Struct({ hello: Schema.String }))
+ * )
+ *
+ * const myHandler = Handler.make(myEndpoint, () => Effect.succeed({ hello: "world" }))
+ *
+ * Effect.gen(function*() {
+ *   const client = yield* NodeTesting.handler(myHandler)
+ *   const response = yield* client(HttpClientRequest.get("/my-endpoint"))
+ *
+ *   assert.deepStrictEqual(response.status, 200)
+ *   assert.deepStrictEqual(yield* response.json, { hello: "world" })
+ * }).pipe(Effect.scoped, Effect.runPromise)
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const handler: <A extends ApiEndpoint.ApiEndpoint.Any, E, R>(
+  app: Handler.Handler<A, E, R>
+) => Effect.Effect<
+  HttpClient.HttpClient.Default,
+  never,
+  | Scope.Scope
+  | Exclude<
+    Exclude<
+      Exclude<R, HttpServerRequest.HttpServerRequest | Scope.Scope>,
+      HttpServer.HttpServer | HttpPlatform.HttpPlatform | Etag.Generator | NodeContext.NodeContext
+    >,
+    NodeContext.NodeContext
+  >
+> = internal.handler

packages/effect-http-node/src/internal/testing.ts

@@ -1,16 +1,22 @@
+import { createServer } from "http"
+
 import * as NodeContext from "@effect/platform-node/NodeContext"
 import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer"
 import type * as HttpApp from "@effect/platform/HttpApp"
 import * as HttpClient from "@effect/platform/HttpClient"
 import * as HttpClientRequest from "@effect/platform/HttpClientRequest"
+import * as HttpRouter from "@effect/platform/HttpRouter"
 import * as HttpServer from "@effect/platform/HttpServer"
-import type * as Api from "effect-http/Api"
-import * as Client from "effect-http/Client"
-import type * as SwaggerRouter from "effect-http/SwaggerRouter"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
-import { createServer } from "http"
+
+import type * as Api from "effect-http/Api"
+import type * as ApiEndpoint from "effect-http/ApiEndpoint"
+import * as Client from "effect-http/Client"
+import * as Handler from "effect-http/Handler"
+import type * as SwaggerRouter from "effect-http/SwaggerRouter"
+
 import * as NodeSwaggerFiles from "../NodeSwaggerFiles.js"
 
 /** @internal */
@@ -27,8 +33,6 @@ const startTestServer = <R, E>(
       Effect.flatMap((url) => Deferred.succeed(allocatedUrl, url)),
       Effect.flatMap(() => Layer.launch(HttpServer.serve(app))),
       Effect.provide(NodeServerLive),
-      Effect.provide(NodeSwaggerFiles.SwaggerFilesLive),
-      Effect.provide(NodeContext.layer),
       Effect.forkScoped,
       Effect.flatMap(() => Deferred.await(allocatedUrl))
     ))
@@ -39,28 +43,54 @@ export const make = <R, E, A extends Api.Api.Any>(
   api: A,
   options?: Partial<Client.Options>
 ) =>
-  Effect.map(startTestServer(app), (url) =>
-    Client.make(api, {
-      ...options,
-      httpClient: (options?.httpClient ?? HttpClient.fetch).pipe(
+  startTestServer(app).pipe(
+    Effect.map((url) =>
+      Client.make(api, {
+        ...options,
+        httpClient: (options?.httpClient ?? HttpClient.fetch).pipe(
+          HttpClient.mapRequest(HttpClientRequest.prependUrl(url)),
+          HttpClient.transformResponse(
+            HttpClient.withFetchOptions({ keepalive: false })
+          )
+        )
+      })
+    ),
+    Effect.provide(NodeSwaggerFiles.SwaggerFilesLive),
+    Effect.provide(NodeContext.layer)
+  )
+
+/** @internal */
+export const makeRaw = <R, E>(
+  app: HttpApp.Default<E, R | SwaggerRouter.SwaggerFiles>
+) =>
+  startTestServer(app).pipe(
+    Effect.map((url) =>
+      HttpClient.fetch.pipe(
         HttpClient.mapRequest(HttpClientRequest.prependUrl(url)),
         HttpClient.transformResponse(
           HttpClient.withFetchOptions({ keepalive: false })
         )
       )
-    }))
+    ),
+    Effect.provide(NodeSwaggerFiles.SwaggerFilesLive),
+    Effect.provide(NodeContext.layer)
+  )
 
 /** @internal */
-export const makeRaw = <R, E>(
-  app: HttpApp.Default<E, R | SwaggerRouter.SwaggerFiles>
+export const handler = <A extends ApiEndpoint.ApiEndpoint.Any, E, R>(
+  handler: Handler.Handler<A, E, R>
 ) =>
-  Effect.map(startTestServer(app), (url) =>
-    HttpClient.fetch.pipe(
-      HttpClient.mapRequest(HttpClientRequest.prependUrl(url)),
-      HttpClient.transformResponse(
-        HttpClient.withFetchOptions({ keepalive: false })
+  startTestServer(HttpRouter.fromIterable([Handler.getRoute(handler)])).pipe(
+    Effect.map((url) =>
+      HttpClient.fetch.pipe(
+        HttpClient.mapRequest(HttpClientRequest.prependUrl(url)),
+        HttpClient.transformResponse(
+          HttpClient.withFetchOptions({ keepalive: false })
+        )
       )
-    ))
+    ),
+    Effect.provide(NodeContext.layer)
+  )
 
 /** @internal */
 const serverUrl = Effect.map(HttpServer.HttpServer, (server) => {