HTTPEx.Backend.Mock (HTTPEx v0.2.0)

View Source

Backend for mocked HTTP requests

Stubbing requests

To add a stubbed request mock, use stub_request!/1. This means that the request may be made but is not asserted.

This is usually done in the beginning of your test suite. These stubs are global and are not isolated. Every test, process etc. will be able to access these.

Asserted requests

To add an assertion, use expect_request!/1. This means that the test will fail, if the HTTP request is not made. This is usally done on a case per case basis in your tests.

These assertions are isolated and are only accessible for the test you are currently running. Processes that were spawned while the test are running, will also be able to access those defined assertions.

Matching and expectations inside defined stubs or assertions

There is a difference between a match and an expectation within a configured mock or expectation. Given the following example:

expect_request!(
  host: "localhost",
  port: 3000,
  response: %{
    status: 200,
    body: "OK"
  }
)

This adds a match on host and port. So every request made to localhost:3000.

When a HTTP call is made, the Mock library will try to look through the registered stubs and asserts and will try find a request that matches the value provided in host.

However, there is also the possibility to assert the actually made request. This is handy when you want to explicitly verify that the request you are making, is using the right payload, headers etc.

expect_request!(
  endpoint: "http://localhost:3000/api/rates",
  expect_body: JSON.encode!(%{"user_id" => "1337"}),
  expect_body_format: :json
)

In this case, the Mock library will match all requests made to port 3000, host localhost, path api/rates. When that request is made, it will verify that the used body matches the one in expect_body. When that is not the case, the test will raise an AssertionError.

Summary

Functions

The inverse of an expected call. Checks that the call (using the matchers) wasn't made.

Adds an asserted request. It will require a match always on endpoint, method and (optional) caller. If you try to add an expected request that already exists, this function will throw an exception.

Returns a response from one of the expectations

Starts the mock registries in a supervisor. We have a server running for the global mocks and local mocks.

Start the HTTPEx Mock server for local expectations.

Start the HTTPEx Mock server for global expectations.

Adds a stubbed HTTP request. Does not check if the request is actually made. This is used to setup basic HTTP requests all your tests can use.

Manually verify made calls

Verifies made HTTP calls. Adds a ExUnit hook and checks if all HTTP calls were actually made.

Functions

assert_no_request!(opts)

@spec assert_no_request!(Keyword.t()) :: :ok | {:error, atom()}

The inverse of an expected call. Checks that the call (using the matchers) wasn't made.

Examples

iex> HTTPEx.Mock.assert_no_request!(
...>   method: :get,
...>   endpoint: "http://www.example.com"
...> )

expect_request!(opts)

@spec expect_request!(Keyword.t()) :: :ok | {:error, atom()}

Adds an asserted request. It will require a match always on endpoint, method and (optional) caller. If you try to add an expected request that already exists, this function will throw an exception.

If you want to explicitly override the request, you must set the allow_override option.

Options

  • body - The request body that is to be matched when an HTTP call is made.

  • body_format - Sets the matching body format. By using this, the matcher can do a safe comparison. This is handy if your fixtures are formatted but your requests are not.

    Can be one of:

    • json
    • xml
    • form
  • description - Described the expectation.

  • expect_body - The request body that is expected to be used.

  • expect_body_format - Sets the expected body format. By using this, the matcher can do a safe comparison. This is handy if your fixtures are formatted but your requests are not.

    Can be one of:

    • json
    • xml
    • form
  • expect_headers - The request headers that are expected to be used.

  • expect_path - The request path that is to be expected to be used.

  • expect_query - The request url query that is to be expected to be used.

  • headers - The request headers that are to be matched when an HTTP call is made.

  • host - The request host that is to be matched when an HTTP call is made. You can also use endpoint instead of this option.

  • endpoint - The request URL that is to be matched when an HTTP call is made.

  • min_calls number() | nil (default 1) - Sets the minimum number of calls that are allowed. If you set this to nil, the request is not mandatory.

  • max_calls number() | nil (default nil) - Sets the maximum number of the times the request can be made.

  • method atom() - The method that is to be matched when an HTTP call is made.

  • path String.t() | function() - The request path that is to be matched when an HTTP call is made. You can also use path instead of this option.

  • port number() - The request port that is to be matched when an HTTP call is made. You can also use endpoint instead of this option.

  • query map() | function() - The url query that is to be matched when an HTTP call is made. You can also pass this down to endpoint or in combination with endpoint.

  • response | {:error, atom() | HTTPoison.Error.t()} - Sets the fake response. Can be one of:

    • }
    • }
    • {:error, :timeout}

    • }

Examples

iex> HTTPEx.Mock.expect_request!(
...>   method: :get,
...>   max_calls: 2,
...>   endpoint: "http://www.example.com",
...>   response: %{status: 200, body: "OK!", headers: [{"Content-Type", "application/json"}]},
...> )

request(request)

Returns a response from one of the expectations

start()

Starts the mock registries in a supervisor. We have a server running for the global mocks and local mocks.

start_assertions()

Start the HTTPEx Mock server for local expectations.

start_stubs()

Start the HTTPEx Mock server for global expectations.

stub_request!(opts)

Adds a stubbed HTTP request. Does not check if the request is actually made. This is used to setup basic HTTP requests all your tests can use.

Examples

iex> HTTPEx.Mock.stub_request!(
...>   method: :get,
...>   endpoint: "http://www.example.com",
...>   response: %{status: 200, body: "OK"}
...> )

Options

See expect_request!/1

verify!(owner_pid \\ self())

Manually verify made calls

verify_on_exit!()

Verifies made HTTP calls. Adds a ExUnit hook and checks if all HTTP calls were actually made.