Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/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.
https://github.com/pspdfkit-labs/bypass
http https mock testing
Last synced: about 1 month ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/pspdfkit-labs/bypass
- Owner: PSPDFKit-labs
- License: mit
- Created: 2015-09-16T16:52:16.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-04-26T15:11:33.000Z (8 months ago)
- Last Synced: 2024-05-18T13:41:46.845Z (7 months ago)
- Topics: http, https, mock, testing
- Language: Elixir
- Homepage: https://hex.pm/packages/bypass
- Size: 6.36 MB
- Stars: 942
- Watchers: 10
- Forks: 107
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - Bypass provides a quick way to create a mock HTTP server with a custom plug. (Testing)
- fucking-awesome-elixir - bypass - Bypass provides a quick way to create a mock HTTP server with a custom plug. (Testing)
- awesome-elixir - bypass - Bypass provides a quick way to create a mock HTTP server with a custom plug. (Testing)
README
# Bypass
[](https://github.com/PSPDFKit-labs/bypass/actions)
[](https://hex.pm/packages/bypass)
[](https://hexdocs.pm/bypass/)
[](https://hex.pm/packages/bypass)
[](https://github.com/PSPDFKit-labs/bypass/blob/master/LICENSE)
[](https://github.com/PSPDFKit-labs/bypass/commits/master)
`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.10 and OTP 21 and up. It works with Cowboy 2.
## Usage
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.
### 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/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
### 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.
```elixir
defmodule TwitterClientTest do
use ExUnit.Case, async: true
setup do
bypass = Bypass.open()
{:ok, bypass: bypass}
end
test "client can handle an error response", %{bypass: bypass} do
Bypass.expect_once(bypass, "POST", "/1.1/statuses/update.json", fn conn ->
Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
end)
{:ok, client} = TwitterClient.start_link(url: endpoint_url(bypass.port))
assert {:error, :rate_limited} == TwitterClient.post_tweet(client, "Elixir is awesome!")
end
test "client can recover from server downtime", %{bypass: bypass} do
Bypass.expect(bypass, fn conn ->
# We don't care about `request_path` or `method` for this test.
Plug.Conn.resp(conn, 200, "")
end)
{:ok, client} = TwitterClient.start_link(url: endpoint_url(bypass.port))
assert :ok == TwitterClient.post_tweet(client, "Elixir is awesome!")
# Blocks until the TCP socket is closed.
Bypass.down(bypass)
assert {:error, :noconnect} == TwitterClient.post_tweet(client, "Elixir is awesome!")
Bypass.up(bypass)
# When testing a real client that is using e.g. https://github.com/fishcakez/connection
# with https://github.com/ferd/backoff to handle reconnecting, we'd have to loop for
# a while until the client has reconnected.
assert :ok == TwitterClient.post_tweet(client, "Elixir is awesome!")
end
defp endpoint_url(port), do: "http://localhost:#{port}/"
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.
> 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:
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.
```elixir
defmodule TwitterClientSpec do
use ESpec, async: true
before do
bypass = Bypass.open()
{:shared, bypass: bypass}
end
finally do
Bypass.verify_expectations!(shared.bypass)
end
specify "the client can handle an error response" do
Bypass.expect_once(shared.bypass, "POST", "/1.1/statuses/update.json", fn conn ->
Plug.Conn.resp(conn, 429, ~s<{"errors": [{"code": 88, "message": "Rate limit exceeded"}]}>)
end)
{:ok, client} = TwitterClient.start_link(url: endpoint_url(shared.bypass.port))
assert {:error, :rate_limited} == TwitterClient.post_tweet(client, "Elixir is awesome!")
end
defp endpoint_url(port), do: "http://localhost:#{port}/"
end
```
## Configuration options
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
```
## Installation
Add `:bypass` to your list of dependencies in mix.exs:
```elixir
def deps do
[
{:bypass, "~> 2.1", 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).
## About
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.
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)).