Awesome

Testing your application's HTTP API endpoint involves coming up with a consistent ways to:

• Construct endpoint paths
• Send requests to your app's request handler
• Parse responses back into Clojure data structures

This is the kind of day-to-day grind that can turn into an unexpected time sink and lead to problems down the line if not done well.

This library does all that for you so that your tests can focus as much as possible on your applciation's business logic and behavior. Instead of writing tests that look like this:

(deftest get-book
  (is (= (->> (mock/request :get (str "/book/" (:book/id book)))
              handler
              :body
              slurp
              (mu/decode "application/transit+json"))
         #:book{:id 0, :title "East of Eden"})))

You can write tests that looks like this:

(deftest get-book
  (is (= (deth/response :get :book {:book/id 0})
         #:book{:id 0 :title "East of Eden"})))

endpoint-test takes care of the machinery of constructing requests, handling them using your application's handler, and reading responses. It's not going to like, change your life, but it'll make it a little nicer.

Example

endpoint-test is meant to be used with donut.system, and it relies on the presence of a ring handler component at [:http :handler] a reitit router component at [:routing :router].

(ns donut.endpoint-test.example
  (:require
   [clojure.test :refer [deftest is use-fixtures]]
   [donut.endpoint.router :as der]
   [donut.endpoint.test.harness :as deth]
   [donut.system :as ds]))

(use-fixtures :each (ds/system-fixture :test))

;; donut.endpoint.test.harness is meant to work with systems defined by
;; donut.system, and with systems

(defmethod ds/named-system :test
  [_]
  {::ds/defs
   {:http
    {:handler
     (ds/ref [:routing :ring-handler])}

    :routing
    {:ring-handler der/RingHandlerComponent
     :router       der/RouterComponent
     :router-opts  der/router-opts
     :routes       [;; returning multiple maps
                    ["/api/v1/books"
                     {:name :books
                      :get  {:handler (fn [_]
                                        {:status 200
                                         :body   [#:book{:id 0 :title "East of Eden"}
                                                  #:book{:id 1 :title "The Martian"}
                                                  #:book{:id 2 :title "Their Eyes Were Watching God"}]})}}]

                    ;; returning a single map
                    ["/api/v1/books/{book/id}"
                     {:name :book
                      :get  {:handler (fn [_]
                                        {:status 200
                                         :body   #:book{:id 0 :title "East of Eden"}})}
                      :put  {:handler (fn [{:keys [all-params]}]
                                        all-params)}}]]}}

   ::ds/plugins
   [deth/test-harness-plugin]})

(deftest get-books
  (is (-> (deth/response :get :books)
          (deth/contains-entity? #:book{:id 0 :title "East of Eden"}))))

(deftest get-book
  (is (= (deth/response :get :book {:book/id 0})
         #:book{:id 0 :title "East of Eden"})))

Usage

All examples assume (require [donut.endpoint.test.harness :as deth]).

Add this fixture to your tests:

(use-fixtures :each (ds/system-fixture :name-of-your-test-system))

This will start a system and bind it to donut.system/*system*, which endpoint-test relies on to get your applications ring handler and router.

If you need to modify your system for your test, you can also use the ds/with-*system* macro:

(deftest get-book
  (ds/with-*system* :test
    (is (= (deth/response :get :book {:book/id 0})
           #:book{:id 0 :title "East of Eden"}))))

Configuring your system

Add deth/test-harness-plugin to your system's plugins:

(defmethod ds/named-system :test
  [_]
  {::ds/defs 
   {}
   
   ::ds/plugins
   [deth/test-harness-plugin]})

This plugin configures your system, setting some default values that the library's helpers rely on to make your tests more concise. It tells the library where to find a router comonent and an http-handler component, and it adds a component that sets the default content type of requests to :transit-json (other values are :json and :html).

Testing requests and responses

endpoint-test offers the following helper functions for creating requests, handling them, and getting responses:

request

This constructs a ring request using ring.mock.request/request. It lets you construct a path using a route name, like so:

(request :get :books)             ;; could use the path "/api/v1/books"
(request :get :book {:book/id 1}) ;; could use the path "/api/v1/books/1"

It also set's the request's content type to whatever your application's :default-request-content-type is (see below.)

handle-request

Creates a request using request and passes it to the ring handler you've defined in your system.

(handle-request :get :books)

read-body

Decodes a response body, traqnsforming it from JSON or whatever back into Clojure.

(read-body (handle-request :get :books))

response

Composition of handle-request and read-body

(deftest get-book
  (is (= (deth/response :get :book {:book/id 0})
         #:book{:id 0 :title "East of Eden"})))

Using the plugin

endpoint-test relies on some configuration within your system to retrieve the components it needs to create request paths with a router and to pass requests to your ring handler. This configuration is provided by deth/test-harness-plugin:

(def test-harness-plugin
  {:donut.system.plugin/name
   ::test-harness-plugin

   :donut.system.plugin/doc
   "Configures system so that donut.endpoint.test.harness can find the
   components needed to construct and dispatch requests."

   :donut.system.plugin/system-defaults
   {::ds/registry {:donut/endpoint-router [:routing :router]
                   :donut/http-handler    [:http :handler]}
    ::ds/defs     {::config {:default-request-content-type :transit-json}}}})

The important part is :donut.system.plugin/system-defaults at the end. Whatever values you set in your system map will take precedence over these values.

Change the value of the component [::deth/config :default-request-content-type] to :json or :html or your own custom content-type if your endpoints return that content and not transit.

Development

Run tests

clojure -X:test