Skip to content

This is the documentation for version 3 of the project. The current version is version 4 and the documentation can be found here.

WPFilesystem module

This module should be used in acceptance and functional tests, see levels of testing for more information.
This module extends the Filesystem module adding WordPress-specific configuration parameters and methods.
The module provides methods to read, write and update the WordPress filesystem directly, without relying on WordPress methods, using WordPress functions or triggering WordPress filters.
This module also provides methods to scaffold plugins and themes on the fly in the context of tests and auto-remove them after each test.

Module requirements for Codeception 4.0+

This module requires the codeception/module-filesystem Composer package to work when wp-browser is used with Codeception 4.0.

To install the package run: 

composer require --dev codeception/module-filesystem:^1.0

Configuration

  • wpRootFolder required The absolute, or relative to the project root folder, path to the root WordPress installation folder. The WordPress installation root folder is the one that contains the wp-load.php file.
  • themes - defaults to /wp-content/themes; the path, relative to the the WordPress installation root folder, to the themes folder.
  • plugins - defaults to /wp-content/plugins; the path, relative to the WordPress installation root folder, to the plugins folder.
  • mu-plugins - defaults to wp-content/mu-plugins; the path, relative to the WordPress installation root folder, to the must-use plugins folder.
  • uploads - defaults to /wp-content/uploads; the path, relative to the WordPress installation root folder, to the uploads folder.

Example configuration

modules:
    enabled:
        - WPFilesystem
    config:
        WPFilesystem:
            wpRootFolder: "/var/www/wordpress"

Public API

amInMuPluginPath

Sets the current working folder to a folder in a mu-plugin.

$I->amInMuPluginPath('mu-plugin');

Parameters

  • string $path - The path to the folder, relative to the mu-plugins root folder.

amInPluginPath

Sets the current working folder to a folder in a plugin.

$I->amInPluginPath('my-plugin');

Parameters

  • string $path - The folder path, relative to the root uploads folder, to change to.

amInThemePath

Sets the current working folder to a folder in a theme.

$I->amInThemePath('my-theme');

Parameters

  • string $path - The path to the theme folder, relative to themes root folder.

amInUploadsPath

Enters, changing directory, to the uploads folder in the local filesystem.

$I->amInUploadsPath('/logs');
  $I->seeFileFound('shop.log');

Parameters

  • string $path - The path, relative to the site uploads folder.

cleanMuPluginDir

Cleans, emptying it, a folder in a mu-plugin folder.

$I->cleanMuPluginDir('mu-plugin1/foo');

Parameters

  • string $dir - The path to the directory, relative to the mu-plugins root folder.

cleanPluginDir

Cleans, emptying it, a folder in a plugin folder.

$I->cleanPluginDir('my-plugin/foo');

Parameters

  • string $dir - The path to the folder, relative to the plugins root folder.

cleanThemeDir

Clears, emptying it, a folder in a theme folder.

$I->cleanThemeDir('my-theme/foo');

Parameters

  • string $dir - The path to the folder, relative to the themese root folder.

cleanUploadsDir

Clears a folder in the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->cleanUploadsDir('some/folder');
  $I->cleanUploadsDir('some/folder', 'today');

Parameters

  • string $dir - The path to the directory to delete, relative to the uploads folder.
  • string/int/[\DateTime](http://php.net/manual/en/class.datetime.php) $date - The date of the uploads to delete, will default to now.

copyDirToMuPlugin

Copies a folder to a folder in a mu-plugin.

$I->copyDirToMuPlugin(codecept_data_dir('foo'), 'mu-plugin/foo');

Parameters

  • string $src - The path to the source file to copy.
  • string $pluginDst - The path to the destination folder, relative to the mu-plugins root folder.

copyDirToPlugin

Copies a folder to a folder in a plugin.

// Copy the 'foo' folder to the 'foo' folder in the plugin.
  $I->copyDirToPlugin(codecept_data_dir('foo'), 'my-plugin/foo');

Parameters

  • string $src - The path to the source directory to copy.
  • string $pluginDst - The destination path, relative to the plugins root folder.

copyDirToTheme

Copies a folder in a theme folder.

$I->copyDirToTheme(codecept_data_dir('foo'), 'my-theme');

Parameters

  • string $src - The path to the source file.
  • string $themeDst - The path to the destination folder, relative to the themes root folder.

copyDirToUploads

Copies a folder to the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->copyDirToUploads(codecept_data_dir('foo'), 'uploadsFoo');
  $I->copyDirToUploads(codecept_data_dir('foo'), 'uploadsFoo', 'today');

Parameters

  • string $src - The path to the source file, relative to the current uploads folder.
  • string $dst - The path to the destination file, relative to the current uploads folder.
  • string/int/[\DateTime](http://php.net/manual/en/class.datetime.php) $date - The date of the uploads to delete, will default to now.

deleteMuPluginFile

Deletes a file in a mu-plugin folder.

$I->deleteMuPluginFile('mu-plugin1/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the mu-plugins root folder.

deletePluginFile

Deletes a file in a plugin folder.

$I->deletePluginFile('my-plugin/some-file.txt');

Parameters

  • string $file - The folder path, relative to the plugins root folder.

deleteThemeFile

Deletes a file in a theme folder.

$I->deleteThemeFile('my-theme/some-file.txt');

Parameters

  • string $file - The path to the file to delete, relative to the themes root folder.

deleteUploadedDir

Deletes a dir in the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->deleteUploadedDir('folder');
  $I->deleteUploadedDir('folder', 'today');

Parameters

  • string $dir - The path to the directory to delete, relative to the uploads folder.
  • string/int/[\DateTime](http://php.net/manual/en/class.datetime.php) $date - The date of the uploads to delete, will default to now.

deleteUploadedFile

Deletes a file in the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->deleteUploadedFile('some-file.txt');
  $I->deleteUploadedFile('some-file.txt', 'today');

Parameters

  • string $file - The file path, relative to the uploads folder or the current folder.
  • string/int $date - A string compatible with strtotime or a Unix timestamp.

dontSeeInMuPluginFile

Checks that a file in a mu-plugin folder does not contain a string.

$I->dontSeeInMuPluginFile('mu-plugin1/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the mu-plugins root folder.
  • string $contents - The contents to check the file for.

dontSeeInPluginFile

Checks that a file in a plugin folder does not contain a string.

$I->dontSeeInPluginFile('my-plugin/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the plugins root folder.
  • string $contents - The contents to check the file for.

dontSeeInThemeFile

Checks that a file in a theme folder does not contain a string.

$I->dontSeeInThemeFile('my-theme/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the themes root folder.
  • string $contents - The contents to check the file for.

dontSeeInUploadedFile

Checks that a file in the uploads folder does contain a string. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->dontSeeInUploadedFile('some-file.txt', 'foo');
  $I->dontSeeInUploadedFile('some-file.txt','foo', 'today');

Parameters

  • string $file - The file path, relative to the uploads folder or the current folder.
  • string $contents - The not expected file contents or part of them.
  • string/int $date - A string compatible with strtotime or a Unix timestamp.

dontSeeMuPluginFileFound

Checks that a file is not found in a mu-plugin folder.

$I->dontSeeMuPluginFileFound('mu-plugin1/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the mu-plugins folder.

dontSeePluginFileFound

Checks that a file is not found in a plugin folder.

$I->dontSeePluginFileFound('my-plugin/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the plugins root folder.

dontSeeThemeFileFound

Checks that a file is not found in a theme folder.

$I->dontSeeThemeFileFound('my-theme/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the themes root folder.

dontSeeUploadedFileFound

Checks thata a file does not exist in the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->dontSeeUploadedFileFound('some-file.txt');
  $I->dontSeeUploadedFileFound('some-file.txt','today');

Parameters

  • string $file - The file path, relative to the uploads folder or the current folder.
  • string/int $date - A string compatible with strtotime or a Unix timestamp.

getBlogUploadsPath

Returns the absolute path to a blog uploads folder or file.

$blogId = $I->haveBlogInDatabase('test');
  $testTodayUploads = $I->getBlogUploadsPath($blogId);
  $testLastMonthLogs = $I->getBlogUploadsPath($blogId, '/logs', '-1 month');
  file or folder.
  sub-folders in the year/month format; a UNIX timestamp or
  a string supported by the `strtotime` function; defaults
  to `now`.

Parameters

  • int $blogId - The blog ID to get the path for.
  • string $file - The path, relatitve to the blog uploads folder, to the
  • null/string/[\DateTime](http://php.net/manual/en/class.datetime.php)/[\DateTime](http://php.net/manual/en/class.datetime.php)Immutable $date - The date that should be used to build the uploads

getUploadsPath

Returns the path to the specified uploads file of folder. Not providing a value for $file and $date will return the uploads folder path.

$todaysPath = $I->getUploadsPath();
  $lastWeek = $I->getUploadsPath('', '-1 week');

Parameters

  • string $file - The file path, relative to the uploads folder.
  • mixed $date - A string compatible with strtotime, a Unix timestamp or a Date object.

getWpRootFolder

Returns the absolute path to WordPress root folder without trailing slash.

$rootFolder = $I->getWpRootFolder();
  $I->assertFileExists($rootFolder . 'wp-load.php');

haveMuPlugin

Creates a mu-plugin file, including plugin header, in the mu-plugins folder. The code can not contain the opening '<?php' tag.

$code = 'echo "Hello world!"';
  $I->haveMuPlugin('foo-mu-plugin.php', $code);
  // Load the code from a file.
  $code = file_get_contents(codecept_data_dir('code/mu-plugin.php'));
  $I->haveMuPlugin('foo-mu-plugin.php', $code);

Parameters

  • string $filename - The path to the file to create, relative to the plugins root folder.
  • string $code - The content of the plugin file with or without the opening PHP tag.

havePlugin

Creates a plugin file, including plugin header, in the plugins folder. The plugin is just created and not activated; the code can not contain the opening '<?php' tag.

$code = 'echo "Hello world!"';
  $I->havePlugin('foo/plugin.php', $code);
  // Load the code from a file.
  $code = file_get_contents(codecept_data_dir('code/plugin.php'));
  $I->havePlugin('foo/plugin.php', $code);

Parameters

  • string $path - The path to the file to create, relative to the plugins folder.
  • string $code - The content of the plugin file with or without the opening PHP tag.

haveTheme

Creates a theme file structure, including theme style file and index, in the themes folder. The theme is just created and not activated; the code can not contain the opening '<?php' tag.

$code = 'sayHi();';
  $functionsCode  = 'function sayHi(){echo "Hello world";};';
  $I->haveTheme('foo', $indexCode, $functionsCode);
  // Load the code from a file.
  $indexCode = file_get_contents(codecept_data_dir('code/index.php'));
  $functionsCode = file_get_contents(codecept_data_dir('code/functions.php'));
  $I->haveTheme('foo', $indexCode, $functionsCode);

Parameters

  • string $folder - The path to the theme to create, relative to the themes root folder.
  • string $indexFileCode - The content of the theme index.php file with or without the opening PHP tag.
  • string $functionsFileCode - The content of the theme functions.php file with or without the opening PHP tag.

makeUploadsDir

Creates an empty folder in the WordPress installation uploads folder.

$logsDir = $I->makeUploadsDir('logs/acme');
  to create.

Parameters

  • string $path - The path, relative to the WordPress installation uploads folder, of the folder

openUploadedFile

Opens a file in the the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->openUploadedFile('some-file.txt');
  $I->openUploadedFile('some-file.txt', 'time');

Parameters

  • string $filename - The path to the file, relative to the current uploads folder.
  • string/int/[\DateTime](http://php.net/manual/en/class.datetime.php) $date - The date of the uploads to delete, will default to now.

seeInMuPluginFile

Checks that a file in a mu-plugin folder contains a string.

$I->seeInMuPluginFile('mu-plugin1/some-file.txt', 'foo');

Parameters

  • string $file - The path the file, relative to the mu-plugins root folder.
  • string $contents - The contents to check the file for.

seeInPluginFile

Checks that a file in a plugin folder contains a string.

$I->seeInPluginFile('my-plugin/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the plugins root folder.
  • string $contents - The contents to check the file for.

seeInThemeFile

Checks that a file in a theme folder contains a string.

<?php
  $I->seeInThemeFile('my-theme/some-file.txt', 'foo');
  ?>

Parameters

  • string $file - The path to the file, relative to the themes root folder.
  • string $contents - The contents to check the file for.

seeInUploadedFile

Checks that a file in the uploads folder contains a string. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->seeInUploadedFile('some-file.txt', 'foo');
  $I->seeInUploadedFile('some-file.txt','foo', 'today');

Parameters

  • string $file - The file path, relative to the uploads folder or the current folder.
  • string $contents - The expected file contents or part of them.
  • string/int $date - A string compatible with strtotime or a Unix timestamp.

seeMuPluginFileFound

Checks that a file is found in a mu-plugin folder.

$I->seeMuPluginFileFound('mu-plugin1/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the mu-plugins folder.

seePluginFileFound

Checks that a file is found in a plugin folder.

$I->seePluginFileFound('my-plugin/some-file.txt');

Parameters

  • string $file - The path to the file, relative to thep plugins root folder.

seeThemeFileFound

Checks that a file is found in a theme folder.

$I->seeThemeFileFound('my-theme/some-file.txt');

Parameters

  • string $file - The path to the file, relative to the themes root folder.

seeUploadedFileFound

Checks if file exists in the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->seeUploadedFileFound('some-file.txt');
  $I->seeUploadedFileFound('some-file.txt','today');
  ?>

Parameters

  • string $filename - The file path, relative to the uploads folder or the current folder.
  • string/int $date - A string compatible with strtotime or a Unix timestamp.

writeToMuPluginFile

Writes a file in a mu-plugin folder.

$I->writeToMuPluginFile('mu-plugin1/some-file.txt', 'foo');

Parameters

  • string $file - The path to the destination file, relative to the mu-plugins root folder.
  • string $data - The data to write to the file.

writeToPluginFile

Writes a file in a plugin folder.

$I->writeToPluginFile('my-plugin/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the plugins root folder.
  • string $data - The data to write in the file.

writeToThemeFile

Writes a string to a file in a theme folder.

$I->writeToThemeFile('my-theme/some-file.txt', 'foo');

Parameters

  • string $file - The path to the file, relative to the themese root folder.
  • string $data - The data to write to the file.

writeToUploadedFile

Writes a string to a file in the the uploads folder. The date argument can be a string compatible with strtotime or a Unix timestamp that will be used to build the Y/m uploads subfolder path.

$I->writeToUploadedFile('some-file.txt', 'foo bar');
  $I->writeToUploadedFile('some-file.txt', 'foo bar', 'today');

Parameters

  • string $filename - The path to the destination file, relative to the current uploads folder.
  • string $data - The data to write to the file.
  • string/int/[\DateTime](http://php.net/manual/en/class.datetime.php) $date - The date of the uploads to delete, will default to now.

This class extends \Codeception\Module\Filesystem