Runs consumer-side contract tests against a Pact mock server.

pact = PactEx.new("web", "users-api")

interaction =
  PactEx.HTTP.interaction("get user")
  |> PactEx.HTTP.with_request(:get, "/users/1")
  |> PactEx.HTTP.will_respond_with(200, body: %{"id" => 1})

PactEx.Consumer.run!(pact, [interaction], fn mock ->
  Req.get!(mock.url <> "/users/1")
end)

run/4 starts a mock server, calls your function, checks that every expected request arrived and that no other did, then writes the pact file. Nothing is written when something did not match.

How interactions are encoded

• Paths, query values and header values are strings or matcher maps (see PactEx.Matchers). Query and header values may also be integers, floats or booleans, which become strings. A list gives a multi-valued parameter. nil, an empty list and other types are rejected: an empty list would drop the parameter without a word.
• Query and header names are strings or atoms. An atom header name is written as Req writes it: underscores become dashes and ASCII letters lower case (:x_request_id is "x-request-id"). Query names and string names are not changed.
• Each request and response has one body content type. The candidates are the :content_type option, the Content-Type header, and the default of the body type. Each is trimmed and the first one that pact_ffi can parse is used, so a type such as "application/json; charset" is skipped. That one string is passed with the body, and when it came from a string header the header is written with it. The header name can be in any case and is written as Content-Type. Its value can be a string, a matcher (its "value" is used) or a list (its first element is used). Two headers that differ only in case are an error. A header that was not the source of the type is sent as you wrote it. A Content-Type value that pact_ffi would turn into an empty list (a map or JSON string with "value" => [], a matcher too) returns {:error, %PactEx.Error{code: -101}}, with or without a body. That holds for any element of a list. As the whole header or the last element, pact_ffi aborts the VM on it. Before a later element, it records an empty string. An empty or whitespace-only string (as the value, an element or a matcher's "value") is rejected too. On a request no request of the interaction can match such a header, and on a response no provider can produce it.
• The default is application/json for a map or list, text/plain for a string that is valid UTF-8 without NUL bytes, and application/octet-stream for any other binary.
• A map or list body is sent as JSON. With an XML content type (application/xml, text/xml, or application/ or text/ with a +xml suffix) or application/x-www-form-urlencoded, pact_ffi reads JSON as a description of the body in its own format. That also applies to a string body that pact_ffi's sniffing takes for JSON. The sniffing reads only the first characters, after optional whitespace: true, false, null, an ASCII digit, a quote, [, or { followed by optional whitespace and then } or a quote and a word character. The rest of the text is not looked at (1=a&2=b counts). pact_ffi panics on some descriptions, which aborts the VM, so PactEx checks them first and returns {:error, %PactEx.Error{code: -101}} naming the interaction and the path of the problem. An XML description is %{"root" => element}, where an element is %{"name" => ..., "attributes" => ..., "children" => [...]}, a text node is %{"content" => ...}, and a matcher element is %{"pact:matcher:type" => ..., "value" => element}. A form description is a map of strings, numbers, matchers with such a value and lists of them (nested maps, booleans, nil and keys that start with "pact:" are errors, because pact_ffi would drop them). A type that is both JSON and XML (application/xml+json) is JSON.
• Every JSON PactEx writes is decoded again and an object that repeats a key is an error at any depth, for every content type. That covers %{a: 1, "a" => 2}, structs that encode to a repeated key, and matcher maps in headers and provider state params.
• A string body is sent byte for byte, except under an XML or form type when pact_ffi's sniffing takes it for JSON. Then it must be a valid JSON description (for example 1=a&2=b under a form type is an error). Any other body type is an error.

The pact file is <pact_dir>/<consumer>-<provider>.json. It is merged with an existing file, so several runs can add interactions to the same pact.