Merge branch 'master' into jv-latest-cowboy

Author: ream88

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## v2.0.0 - TBA
+## v2.0.0 - 19 Aug 2020
 
 * Allow the redefinition of routes.
 * Make listen interface configurable.

README.md

@@ -2,119 +2,43 @@
 
 [![Build Status](https://travis-ci.org/PSPDFKit-labs/bypass.svg?branch=master)](https://travis-ci.org/PSPDFKit-labs/bypass)
 
-Bypass provides a quick way to create a custom plug that can be put in place instead of an actual
-HTTP server to return prebaked responses to client requests. This is most useful in tests, when you
-want to create a mock HTTP server and test how your HTTP client handles different types of
-responses from the server.
+[Online Documentation](https://hexdocs.pm/bypass).
 
-## Installation
+<!-- MDOC !-->
 
-Add bypass to your list of dependencies in mix.exs:
-
-```elixir
-def deps do
-  [
-    {:bypass, "~> 1.0", only: :test}
-  ]
-end
-```
-
-We do not recommended adding `:bypass` to the list of applications in your `mix.exs`. See below
-for usage info.
+`Bypass` provides a quick way to create a custom plug that can be put in place
+instead of an actual HTTP server to return prebaked responses to client
+requests. This is most useful in tests, when you want to create a mock HTTP
+server and test how your HTTP client handles different types of responses from
+the server.
 
 Bypass supports Elixir 1.6 and OTP 20 and up. It works with Cowboy 1 and 2.
 
-
 ## Usage
 
-To use Bypass in a test case, open a connection and use its port to connect your client to it.
+To use Bypass in a test case, open a connection and use its port to connect your
+client to it.
 
-If you want to test what happens when the HTTP server goes down, use `Bypass.down/1` to close the
-TCP socket and `Bypass.up/1` to start listening on the same port again. Both functions block until
-the socket updates its state.
+If you want to test what happens when the HTTP server goes down, use
+`Bypass.down/1` to close the TCP socket and `Bypass.up/1` to start listening on
+the same port again. Both functions block until the socket updates its state.
 
 ### Expect Functions
 
 You can take any of the following approaches:
-* `expect/2` or `expect_once/2` to install a generic function that all calls to bypass will use
+
+* `expect/2` or `expect_once/2` to install a generic function that all calls to
+  bypass will use
 * `expect/4` and/or `expect_once/4` to install specific routes (method and path)
 * `stub/4` to install specific routes without expectations
-* a combination of the above, where the routes will be used first, and then the generic version
-  will be used as default
-
-#### expect/2 (bypass_instance, function)
-
-Must be called at least once.
-
-```elixir
-Bypass.expect(bypass, fn conn ->
-  assert "/1.1/statuses/update.json" == conn.request_path
-  assert "POST" == conn.method
-  Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
-end)
-```
-
-#### expect_once/2 (bypass_instance, function)
-
-Must be called exactly once.
-
-```elixir
-Bypass.expect_once(bypass, fn conn ->
-  assert "/1.1/statuses/update.json" == conn.request_path
-  assert "POST" == conn.method
-  Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
-end)
-```
-
-#### expect/4 (bypass_instance, method, path, function)
-
-Must be called at least once.
-
-`method` is one of `["GET", "POST", "HEAD", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT"]`
-
-`path` is the endpoint.
-
-```elixir
-Bypass.expect(bypass, "POST", "/1.1/statuses/update.json", fn conn ->
-  Agent.get_and_update(AgentModule, fn step_no -> {step_no, step_no + 1} end)
-  Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
-end)
-```
-
-#### expect_once/4 (bypass_instance, method, path, function)
-
-Must be called exactly once.
-
-`method` is one of `["GET", "POST", "HEAD", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT"]`
-
-`path` is the endpoint.
-
-```elixir
-Bypass.expect_once(bypass, "POST", "/1.1/statuses/update.json", fn conn ->
-  Agent.get_and_update(AgentModule, fn step_no -> {step_no, step_no + 1} end)
-  Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
-end)
-```
-
-#### stub/4 (bypass_instance, method, path, function)
-
-May be called none or more times.
-
-`method` is one of `["GET", "POST", "HEAD", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT"]`
-
-`path` is the endpoint.
-
-```elixir
-Bypass.stub(bypass, "POST", "/1.1/statuses/update.json", fn conn ->
-  Agent.get_and_update(AgentModule, fn step_no -> {step_no, step_no + 1} end)
-  Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
-end)
-```
+* a combination of the above, where the routes will be used first, and then the
+  generic version will be used as default
 
 ### Example
 
-In the following example `TwitterClient.start_link()` takes the endpoint URL as its argument
-allowing us to make sure it will connect to the running instance of Bypass.
+In the following example `TwitterClient.start_link()` takes the endpoint URL as
+its argument allowing us to make sure it will connect to the running instance of
+Bypass.
 
 ```elixir
 defmodule TwitterClientTest do
@@ -162,33 +86,31 @@ defmodule TwitterClientTest do
 end
 ```
 
-That's all you need to do. Bypass automatically sets up an `on_exit` hook to close its socket when
-the test finishes running.
-
-Multiple concurrent Bypass instances are supported, all will have a different unique port.  Concurrent
-requests are also supported on the same instance.
-
-In case you need to assign a specific port to a Bypass instance to listen on, you can pass the
-`port` option to `Bypass.open()`:
+That's all you need to do. Bypass automatically sets up an `on_exit` hook to
+close its socket when the test finishes running.
 
-```elixir
-bypass = Bypass.open(port: 1234)
-```
+Multiple concurrent Bypass instances are supported, all will have a different
+unique port.  Concurrent requests are also supported on the same instance.
 
-> Note: `Bypass.open/0` **must not** be called in a `setup_all` blocks due to the way Bypass verifies the expectations at the end of each
-> test.
+> Note: `Bypass.open/0` **must not** be called in a `setup_all` blocks due to
+> the way Bypass verifies the expectations at the end of each test.
 
 ## How to use with ESpec
 
-While Bypass primarily targets ExUnit, the official Elixir builtin test framework, it can also be used with [ESpec](https://hex.pm/packages/espec). The test configuration is basically the same, there are only two differences:
+While Bypass primarily targets ExUnit, the official Elixir builtin test
+framework, it can also be used with [ESpec](https://hex.pm/packages/espec). The
+test configuration is basically the same, there are only two differences:
 
-1. In your Mix config file, you must declare which test framework Bypass is being used with (defaults to `:ex_unit`). This simply disables the automatic integration with some hooks provided by `ExUnit`.
+1. In your Mix config file, you must declare which test framework Bypass is
+   being used with (defaults to `:ex_unit`). This simply disables the automatic
+   integration with some hooks provided by `ExUnit`.
 
 ```elixir
 config :bypass, test_framework: :espec
 ```
 
-2. In your specs, you must explicitly verify the declared expectations. You can do it in the `finally` block.
+2. In your specs, you must explicitly verify the declared expectations. You can
+   do it in the `finally` block.
 
 ```elixir
 defmodule TwitterClientSpec do
@@ -218,12 +140,30 @@ end
 
 ## Configuration options
 
-Set `:enable_debug_log` to `true` in the application environment to make Bypass log what it's doing:
+Set `:enable_debug_log` to `true` in the application environment to make Bypass
+log what it's doing:
 
 ```elixir
 config :bypass, enable_debug_log: true
 ```
 
+<!-- MDOC !-->
+
+## Installation
+
+Add bypass to your list of dependencies in mix.exs:
+
+```elixir
+def deps do
+  [
+    {:bypass, "~> 2.0", only: :test}
+  ]
+end
+```
+
+We do not recommended adding `:bypass` to the list of applications in your
+`mix.exs`.
+
 ## License
 
 This software is licensed under [the MIT license](LICENSE).
@@ -236,8 +176,10 @@ This software is licensed under [the MIT license](LICENSE).
 
 This project is maintained and funded by [PSPDFKit](https://pspdfkit.com/).
 
-Please ensure
-[you signed our CLA](https://pspdfkit.com/guides/web/current/miscellaneous/contributing/) so we can
-accept your contributions.
+Please ensure [you signed our
+CLA](https://pspdfkit.com/guides/web/current/miscellaneous/contributing/) so we
+can accept your contributions.
 
-See [our other open source projects](https://github.com/PSPDFKit-labs), read [our blog](https://pspdfkit.com/blog/) or say hello on Twitter ([@PSPDFKit](https://twitter.com/pspdfkit)).
+See [our other open source projects](https://github.com/PSPDFKit-labs), read
+[our blog](https://pspdfkit.com/blog/) or say hello on Twitter
+([@PSPDFKit](https://twitter.com/pspdfkit)).