library php-vcr

php-vcr/php-vcr

Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests.

, _(*1)

, _(*2)

This is a port of the VCR Ruby library to PHP., _(*3)

Record your test suite's HTTP interactions and replay them during future test runs for fast, deterministic, accurate tests. A bit of documentation can be found on the php-vcr website., _(*4)

Disclaimer: Doing this in PHP is not as easy as in programming languages which support monkey patching (I'm looking at you, Ruby), _(*5)

Features

• Automatically records and replays your HTTP(s) interactions with minimal setup/configuration code.
• Supports common http functions and extensions
  • everything using streamWrapper: fopen(), fread(), file_get_contents(), ... without any modification (except $http_response_header see #96)
  • SoapClient by adding \VCR\VCR::turnOn(); in your tests/bootstrap.php
  • curl(), by adding \VCR\VCR::turnOn(); in your tests/bootstrap.php
• The same request can receive different responses in different tests -- just use different cassettes.
• Disables all HTTP requests that you don't explicitly allow by setting the record mode
• Request matching is configurable based on HTTP method, URI, host, path, body and headers, or you can easily implement a custom request matcher to handle any need.
• The recorded requests and responses are stored on disk in a serialization format of your choice (currently YAML and JSON are built in, and you can easily implement your own custom serializer)
• Supports PHPUnit annotations.

Usage example

Using static method calls:, _(*6)

``` php class VCRTest extends TestCase { public function testShouldInterceptStreamWrapper() { // After turning on the VCR will intercept all requests \VCR\VCR::turnOn();, <sub>(*7)</sub>

    // Record requests and responses in cassette file 'example'
    \VCR\VCR::insertCassette('example');

    // Following request will be recorded once and replayed in future test runs
    $result = file_get_contents('http://example.com');
    $this->assertNotEmpty($result);

    // To stop recording requests, eject the cassette
    \VCR\VCR::eject();

    // Turn off VCR to stop intercepting requests
    \VCR\VCR::turnOff();
}

public function testShouldThrowExceptionIfNoCasettePresent()
{
    $this->setExpectedException(
        'BadMethodCallException',
        "Invalid http request. No cassette inserted. Please make sure to insert "
        . "a cassette in your unit test using VCR::insertCassette('name');"
    );
    \VCR\VCR::turnOn();
    // If there is no cassette inserted, a request throws an exception
    file_get_contents('http://example.com');
}

}, <sub>(*8)</sub>

You can use annotations in PHPUnit by using [phpunit-testlistener-vcr](https://github.com/php-vcr/phpunit-testlistener-vcr):

``` php
class VCRTest extends TestCase
{
    /**
     * @vcr unittest_annotation_test
     */
    public function testInterceptsWithAnnotations()
    {
        // Requests are intercepted and stored into  tests/fixtures/unittest_annotation_test.
        $result = file_get_contents('http://google.com');

        $this->assertEquals('This is a annotation test dummy.', $result, 'Call was not intercepted (using annotations).');

        // VCR is automatically turned on and off.
    }
}

Installation

Simply run the following command:, <sub>(*9)</sub>

``` bash $ composer require --dev php-vcr/php-vcr, <sub>(*10)</sub>

## Dependencies

PHP-VCR depends on:

  * PHP 8
  * Curl extension
  * [symfony/event-dispatcher](https://github.com/symfony/event-dispatcher)
  * [symfony/yaml](https://github.com/symfony/yaml)
  * [beberlei/assert](https://github.com/beberlei/assert)

Composer installs all dependencies except extensions like curl.

## Run tests

In order to run all tests you need to get development dependencies using composer:

``` php
composer install
composer test

Changelog

The changelog has moved to the PHP-VCR releases page., <sub>(*11)</sub>

Old changelog entries, <sub>(*12)</sub>

Copyright

Copyright (c) 2013-2023 Adrian Philipp. Released under the terms of the MIT license. See LICENSE for details. Contributors, <sub>(*13)</sub>