Trying to test filesystem operations with VFSStream

I'm trying to mock a filesystem operation (well actually a read from php://input) with vfsStream but the lack of decent documentation and examples is really hampering me.

The relevant code from the class I'm testing is as follows:

class RequestBody implements iface\request\RequestBody
{
    const
        REQ_PATH    = 'php://input',

    protected
        $requestHandle  = false;

    /**
     * Obtain a handle to the request body
     * 
     * @return resource a file pointer resource on success, or <b>FALSE</b> on error.
     */
    protected function getHandle ()
    {
        if (empty ($this -> requestHandle))
        {
            $this -> requestHandle  = fopen (static::REQ_PATH, 'rb');
        }
        return $this -> requestHandle;
    }
}

The setup I'm using in my PHPUnit test is as follows:

protected function configureMock ()
{
    $mock   = $this -> getMockBuilder ('\gordian\reefknot\http\request\RequestBody');

    $mock   -> setConstructorArgs (array ($this -> getMock ('\gordian\reefknot\http\iface\Request')))
            -> setMethods (array ('getHandle'));


    return $mock;
}

/**
 * Sets up the fixture, for example, opens a network connection.
 * This method is called before a test is executed.
 */
protected function setUp ()
{
    \vfsStreamWrapper::register();
    \vfsStream::setup ('testReqBody');

    $mock   = $this -> configureMock ();
    $this -> object = $mock -> getMock ();

    $this -> object -> expects ($this -> any ())
                    -> method ('getHandle')
                    -> will ($this -> returnCallback (function () {
                        return fopen ('vfs://testReqBody/data', 'rb');
                    }));
}

In an actual test (which calls a method which indirectly triggers getHandle()) I try to set up the VFS and run an assertion as follows:

public function testBodyParsedParsedTrue ()
{
    // Set up virtual data
    $fh     = fopen ('vfs://testReqBody/data', 'w');
    fwrite ($fh, 'test write 42');
    fclose ($fh);
    // Make assertion
    $this -> object -> methodThatTriggersGetHandle ();
    $this -> assertTrue ($this -> object -> methodToBeTested ());
}

This just causes the test to hang.

Obviously I'm doing something very wrong here, but given the state of the documentation I'm unable to work out what it is I'm meant to be doing. Is this something caused by vfsstream, or is phpunit mocking the thing I need to be looking at here?

Solution

So ... how to test with streams? All vfsStream does is provide a custom stream wrapper for file system operations. You don't need the full-blown vfsStream library just to mock the behavior of a single stream argument -- it's not the correct solution. Instead, you need to write and register your own one-off stream wrapper because you aren't trying to mock file system operations.

Say you have the following simple class to test:

class ClassThatNeedsStream {
    private $bodyStream;
    public function __construct($bodyStream) {
        $this->bodyStream = $bodyStream;
    }
    public function doSomethingWithStream() {
        return stream_get_contents($this->bodyStream);
    }
}

In real life you do:

$phpInput = fopen('php://input', 'r');
new ClassThatNeedsStream($phpInput);

So to test it, we create our own stream wrapper that will allow us to control the behavior of the stream we pass in. I can't go into too much detail because custom stream wrappers are a large topic. But basically the process goes like this:

Create custom stream wrapper
Register that stream wrapper with PHP
Open a resource stream using the registered stream wrapper scheme

So your custom stream looks something like:

class TestingStreamStub {

    public $context;
    public static $position = 0;
    public static $body = '';

    public function stream_open($path, $mode, $options, &$opened_path) {
        return true;
    }

    public function stream_read($bytes) {
        $chunk = substr(static::$body, static::$position, $bytes);
        static::$position += strlen($chunk);
        return $chunk;
    }

    public function stream_write($data) {
        return strlen($data);
    }

    public function stream_eof() {
        return static::$position >= strlen(static::$body);
    }

    public function stream_tell() {
        return static::$position;
    }

    public function stream_close() {
        return null;
    }
}

Then in your test case you would do this:

public function testSomething() {
    stream_wrapper_register('streamTest', 'TestingStreamStub');
    TestingStreamStub::$body = 'my custom stream contents';
    $stubStream = fopen('streamTest://whatever', 'r+');

    $myClass = new ClassThatNeedsStream($stubStream);
    $this->assertEquals(
        'my custom stream contents',
        $myClass->doSomethingWithStream()
    );

    stream_wrapper_unregister('streamTest');
}

Then, you can simply change the static properties I've defined in the stream wrapper to change what data comes back from reading the stream. Or, extend your base stream wrapper class and register it instead to provide different scenarios for tests.

This is a very basic intro, but the point is this: don't use vfsStream unless you're mocking actual filesystem operations -- that's what it's designed for. Otherwise, write a custom stream wrapper for testing.

PHP provides a prototype stream wrapper class to get you started: http://www.php.net/manual/en/class.streamwrapper.php