Download the PHP package 2pd/guzzle-http-mock without Composer

GuzzleHttpMock

A mock library for verifying requests made with the Guzzle Http Client, and mocking responses.

This is a fork of the original version. This version was changed to support Guzzle 6 and did receive some other minor changes.

• Installation
  • Composer
• Overview
  • How does it work?
• Usage
  • Attaching to a Guzzle Client
  • Creating Request Expectations
    • Available Expectations
    • Default Expectations
    • Directly Setting an Expected Request
    • Custom Expectations
  • Mocking Responses
  • Verifying Expectations
  • Gotchyas
  • Unspecified expectations
  • Where's my UnexpectedRequestException?
  • Why's it doing that thing I don't think it should do?
  • Contributing
  • Wish List

Installation

Composer

You can install GuzzleHttpMock using composer:

Overview

GuzzleHttpMock allows you to setup Http request expectations, and mock responses.

How does it work?

When a GuzzleHttpMock Handler is attached to the Guzzle Http client, it will intercept all requests made by the client. Whenever a request is made, the mock checks the request against set expectations, and sends a response to matching requests. If your client uses custom middleware you can attach it to the handler stack of the mock handler.

Calling $httpMock->verify() checks that all expected requests have been made, and complains about any unexpected requests.

Usage

Attaching to a Guzzle Client

To start intercepting Http requests, the GuzzleHttpMock must be attached to a GuzzleClient:

Creating Request Expectations

The shouldReceiveRequest method returns a \Aeris\GuzzleHttpMock\Expectation\RequestExpectation object.

The RequestExpectation object uses withXyz methods to set expectations:

The expectation setters are chainable, allowing for a fluid interface:

Available Expectations

The following expectations are available on a \Aeris\GuzzleHttpMock\Expectation\RequestExpectation object.

Default Expectations

By default, a request is expected to be made one time, with an Http method of 'GET'.

Directly Setting an Expected Request

In addition to specifying request expectations individually, you can also directly set a Psr\Http\Message\RequestInterface object as an expectation.

Custom Expectations

All expectation methods accept either a value or a callable as a parameter. By passing a callable, you can create custom expectations. For example:

In this case, the expectation will fail if the actual request body has a foo params which does not equal bar.

GuzzleHttpMock provides some built-in custom expectations, as well. For example:

Mocking Responses

When a request is made which matches an expectation, the GuzzleHttpMock will intercept the request, and respond with a mock response.

Available Responses

The following methods are available for mocking responses:

Directly Setting a Mock Response

You may mock a response directly using a response object:

Verifying Expectations

Expectations may be verified using the \Aeris\GuzzleHttpMock::verify() method.

With PHPUnit

When using GuzzleHttpMock with PHPUnit, make sure to add Mock::verify() to your teardown:

Gotchyas

We have used GuzzleHttpMock enough internally to feel comfortable using it on production projects, but also enough to know that there are a few "gotchyas". Hopefully, knowing these issues up-front will prevent much conflict between your forehead and your desk.

If you'd like to take a shot at resolving any of these issues, take a look at our contribution guidelines.

Unspecified expectations

In the current version of GuzzleHttpMock, any expectations which are not specified will result in a failed request.

You might argue that it would make more sense for the RequestExpectation to accept any value for unspecified expectations by default. And you might be right. Future versions of GuzzleHttpMock may do just that.

Where's my UnexpectedRequestException?

There are a couple of possible culprits here:

1. Make sure you're calling Mock::verify(). If you're using a testing framework (eg PHPUnit), you can put verify() in the tearDown method.

2. Another exception may be thrown before you had a chance to verify your request expectations.

Solving #2 can be a little tricky. If a RequestExpectation cannot be matched, GuzzleHttpClient will not respond with your mock response, which may cause other code to break before you have a chance to call verify().

If you're calling verify() in your test tearDown, you may want to try adding another verify() call immediately after the http request is made.

You can also try wrapping the offending code in a try...catch block, to give the UnexpectedRequestException priority.

That's more verbosity than you may want in all of your tests, but it can be helpful if you're debugging.

Why's it doing that thing I don't think it should do?

I don't know. That's really weird. Bummer...

Hey, why don't you open a new issue and tell us about it? Maybe we can help.

Contributing

For that warm fuzzy open-sourcey feeling, contribute to GuzzleHttpMock today!

We only ask that you include PHPUnit tests, and update documentation as needed. Also, if it's not an open issue or on our wish list, you might want to open an issue first, to make sure you're headed in the right direction.

Wish List

Take a look at the "Gotchyas" section for some things that could be fixed. Have another idea? Open an issue, and we'll talk.