@@ -153,7 +153,8 @@ Hmm. One passed and one failed! It looks like I *was* expecting a success
153153response in the second test, but I actually got a failure. We should fix that,
154154but first I'd like to introduce `hspec-wai`, which will give us different
155155mechanisms for making requests of our application and validating the responses
156−we get.
156+we get. We're also going to spin up a fake Elasticsearch server, so that our
157+server can think it's talking to a real database.
157158
158159
159160## *Mocking* 3rd Party Resources
@@ -201,11 +202,13 @@ build a simple app server that uses this client to retrieve documents. This
201202is somewhat contrived, but hopefully it illustrates the typical three-tier
202203application architecture.
203204
204−One note: we're also going to take advantage of `aeson-lens` here, which may
205+One note: we're also going to take advantage of `lens-aeson` here, which may
205206look a bit foreign. The gist of it is that we're going to traverse a JSON
206207`Value` from Elasticsearch and try to extract some kind of document to
207208return.
208209
210+Imagine, then, that this is our real server implementation:
211+
209212```haskell
210213type DocApi =
211214 "docs" :> Capture "docId" Integer :> Get '[JSON] Value
@@ -232,7 +235,7 @@ getDocById esHost esPort docId = do
232235### Testing Our Backend
233236
234237So the above represents our application and is close to a server we may
235−actually deploy. How shall we test this application?
238+actually deploy. How then shall we test this application?
236239
237240Ideally, we'd like it to make requests of a *real* Elasticsearch server, but
238241we certainly don't want our tests to trigger requests to a live, production
@@ -284,7 +287,7 @@ Hopefully, this will simplify our testing code:
284287```haskell
285288thirdPartyResourcesSpec :: Spec
286289thirdPartyResourcesSpec = around_ withElasticsearch $ do
287− -- we call `with` and pass our servant-server `Application`
290+ -- we call `with` and pass our own servant-server `Application`
288291 with (pure $ serve (Proxy :: Proxy DocApi) $ docServer "localhost" "9999") $ do
289292 describe "GET /docs" $ do
290293 it "should be able to get a document" $
@@ -310,10 +313,10 @@ bodyMatcher _ body = case (decode body :: Maybe Value) of
310313 -- success in this case means we return `Nothing`
311314 Just val | val == (Object $ HM.fromList [("a", String "b")]) -> Nothing
312315 _ -> Just "This is how we represent failure: this message will be printed"
313−
314316```
315317
316−What happens when we run these tests?
318+Out of the box, `hspec-wai` provides a lot of useful tools for us to run tests
319+against our application. What happens when we run these tests?
317320
318321```
319322$ cabal new-test all
@@ -327,7 +330,8 @@ GET /docs
327330 we can also do more with the Response using hspec-wai's matchers
328331```
329332
330−Fortunately, they all passed!
333+Fortunately, they all passed! Let's move to another strategy: whole-API
334+testing.
331335
332336## Servant Quickcheck
333337
@@ -335,13 +339,13 @@ Fortunately, they all passed!
335339is a project that allows users to write tests for whole Servant APIs using
336340quickcheck-style property-checking mechanisms.
337341
338−`servant-quickcheck` is great for asserting whole-API rules, such as "no
342+`servant-quickcheck` is great for asserting API-wide rules, such as "no
339343endpoint throws a 500" or "all 301 status codes also come with a Location
340344header". The project even comes with a number of predicates that reference
341345the [RFCs they originate from](https://github.com/haskell-servant/servant-quickcheck/blob/master/src/Servant/QuickCheck/Internal/Predicates.hs).
342346
343−Thus, it's one way to assert that your APIs conform to specs and best
344−practices.
347+In other words, it's one way to assert that your APIs conform to specs and
348+best practices.
345349
346350### Quickcheckable API
347351
@@ -389,7 +393,7 @@ servantQuickcheckSpec = describe "" $ do
389393 -- `serverSatisfies` and the predicates also come from `servant-quickcheck`
390394 serverSatisfies api burl args (unauthorizedContainsWWWAuthenticate
391395 <%> not500
392− <%> onlyJsonObjects
396+ <%> onlyJsonObjects -- this one isn't true!
393397 <%> mempty)
394398
395399 it "API doesn't have these things implemented yet" $
@@ -428,7 +432,7 @@ Randomized with seed 1046277487
428432Finished in 0.4306 seconds
429433```
430434
431−Hmm. It looks like we *thought* our API only return JSON objects, which is a
435+Hmm. It looks like we *thought* our API only returned JSON objects, which is a
432436best practice, but in fact, we *did* have an endpoint that returned an empty
433437body, which you can see in the printed response above: `Body: ""`. We should
434438consider revising our API to only return top-level JSON Objects in the future!