FileSystemFixtureTools are used to test classes which interact with the filesystem. Fixture files and dirs are organised in a designated sandbox and everything is automatically cleared up at the end of each test.
Add the tools to a test case in a beforeInvoking() method, like this:
<?php
class YourTestCase extends AperiUnitTest {
function beforeInvoking() {
$this->mixin('FileSystemFixtureTools');
}
...
...
All FileSystemFixtureTools methods are now available to be called in the test case, as if they were methods of the test case (more here).
If the fixtures are complex, and/or you need to re-use them in other test cases, you can write a fixture class and add it after the fixture tools:
<?php
class YourTestCase extends AperiUnitTest {
function beforeInvoking() {
$this->mixin('FileSystemFixtureTools');
$this->addFixture(new MyFixture);
}
...
...
sandbox() - returns the path to the sandbox dir
(see below)createDir($path) - creates intermediate dirs in the path
like the unix command: "mkdir -p"createFile( - creates intermediate dirs when they
$path, don't exist
$contents = '',
$mode = 'w')edit( - this is actually identical to createFile
$path, but sometimes the intent is clearer with
$contents = '', "edit"
$mode = 'w')createLink( - creates intermediate dirs when they don't
$target, exist
$link)cache($path) - Add a given path to the stat cache. You could
simply write filetype($path) (or etc) but that
might not explain the intent so well.
If you're wondering which of the php
stat-cache-inducing methods are called by cache()
the answer is all of them.
Remember that the stat cache stores literal
strings: relative and absolute forms are seen
as two different paths.
To clear the cache just call clearstatcache(),
as normal. Note that clearstatcache() is always
called by the test framework before setup().
Also, an unlink() call will clear all records
in the cache, not just the unlinked path.dumpDir($path) - show directory contents
dumpFile($path) - show file contents
assertPath( - a clearstatcache() call ensures that the
$path, filesystem is checked and not the stat cache
$type = '', - optionally specify the type (file, link, or dir)
$message = '%s')assertNoPath( - ditto
$path,
$message = '%s')assertEmptyDir(
$path, - $path is a directory path
$message = '%s')assertContents(
$path,
$expected, - the full file_get_contents string
$message = '%s')assertContains(
$path,
$needle, - $needle is a text string not a regex
$count = '>=1', - optionally specify num matches (int) default is >= 1
$message = '%s')
A sandbox dir is automatically created before setUp() and destroyed after tearDown(). You won't need to clear up any fixture files or dirs manually (provided that they were created in the sandbox..).
Fatal errors mean that the script will exit without having a chance to clear up. Abandoned fixtures will be identified and removed the next time the script is run.
By default the class gets the sandbox path from an AperiRegistry instance. A config file would define a sandbox dir:
<?php
$registry->set('sandbox-dir', '/mnt/sandbox/testing/');
...
...
Requiring the use of AperiRegistry is a bit of an imposition. You can substitute your own preferred solution simply by overriding the method: FileSystemFixtureTools::sandbox().
The sandbox parent dir must be writable by the php process (so you can create the sandbox...) but the dir above that should not. In the worst case, you might be testing some kind of recursive delete which goes haywire, escapes the sandbox, and tries to delete all your files. Permissions help to prevent this. On windows, the safest thing to do is to set aside a small partition for testing only. Neither is foolproof.
A tmpfs filesystem might be a good option for the sandbox. In practice, it might not make much difference to performance, depednding on what you're doing.
At present, all path args (in the fixture creation methods & assertions, above) are masked to the sandbox path. I'm having second thoughts about that though. What do you think?
"Sandbox path exists" is a skip condition. Hence, if the sandbox path has mistakenly been set to something catastrophic like c: or "/" FileSystemFixtureTools will not attempt to delete all your files at tearDown().
The test case will also skip if the sandbox parent dir is not writable.