wp-browser

https://github.com/lucatume/wp-browser
Admin
A set of Codeception modules to test WordPress projects with end-to-end, integration, and unit tests...
Tokens:178,012
Snippets:1,608
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configuration for dev:start services

Source: https://github.com/lucatume/wp-browser/blob/master/docs/commands.md

Example configuration for the extensions section that defines the services to be started by dev:start. The services are read from the config key.

```yaml
extensions:
  enabled:
    - lucatume\WPBrowser\Extension\ChromeDriverController
    - lucatume\WPBrowser\Extension\BuiltInServerController
    - lucatume\WPBrowser\Extension\DockerComposeController
  config:
    "lucatume\\WPBrowser\\Extension\\ChromeDriverController":
      port: '%CHROMEDRIVER_PORT%'
    "lucatume\\WPBrowser\\Extension\\BuiltInServerController":
      docroot: '%WORDPRESS_ROOT_DIR%'
      workers: 5
      port: '%BUILT_IN_SERVER_PORT%'
    "lucatume\\WPBrowser\\Extension\\DockerComposeController":
      compose-file: 'tests/docker-compose.yml'
      env-file: 'tests/.env'
```

--------------------------------

### MySqlServerController configuration for all suites

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/MySqlServerController.md

Example configuration starting the server for all suites. The extension will start and stop the MySQL server before and after the tests run, downloading and initializing the server in the `_mysql-server` directory under the codeception output directory.

```yaml
extensions:
  enabled:
    - "lucatume\WPBrowser\Extension\MySqlServerController":
      port: 8906
      database: wordpress
      user: wordpress
      password: wordpress
```

--------------------------------

### GitHub Actions workflow for wp-browser tests

Source: https://github.com/lucatume/wp-browser/blob/master/docs/default-configuration.md

Example workflow that runs the default self-contained configuration on GitHub Actions. It sets up PHP with SQLite extensions, installs dependencies, rebuilds the WordPress installation, installs Chromedriver, and runs tests. The PHP built-in server and Chromedriver start automatically during the end-to-end suite.

```yaml
name: Tests
on: [push, pull_request]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: sqlite3, pdo_sqlite
          coverage: none

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Build the WordPress installation
        run: vendor/bin/codecept dev:rebuild

      - name: Install Chromedriver
        run: vendor/bin/codecept chromedriver:update --binary "$(which google-chrome)"

      - name: Run tests
        run: vendor/bin/codecept run
```

--------------------------------

### ChromeDriverController configuration for all suites

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/ChromeDriverController.md

Example configuration that starts the ChromeDriver server for all suites, setting the port to 4444 and the binary path to /usr/local/bin/chromedriver.

```yaml
extensions:
  enabled:
    - "lucatume\\WPBrowser\\Extension\\ChromeDriverController"
  config:
    "lucatume\\WPBrowser\\Extension\\ChromeDriverController":
      port: 4444
      binary: /usr/local/bin/chromedriver
```

--------------------------------

### dontSeePluginInstalled example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Asserts a plugin is not installed in the plugins administration screen. The method does not handle authentication or navigation, so login and navigation must be done beforehand.

```php
<?php
$I->loginAsAdmin();
$I->amOnPluginsPage();
$I->dontSeePluginInstalled('my-plugin');
```

--------------------------------

### assertQueriesByStatement example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least one query starting with SELECT was made. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
wp_cache_flush();
cached_get_posts($args);
$I->assertQueriesByStatement('SELECT');
```

--------------------------------

### WPLoader integration suite configuration with MySQL

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPLoader.md

Example of an integration suite configured to use the WPLoader module with a MySQL database. Shows how to specify plugins from various locations (WordPress installation, absolute path, relative path, project root) and load a theme from the WordPress installation themes directory.

```yaml
actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: mysql://root:root@mysql:3306/wordpress
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          # This plugin will be loaded from the WordPress installation plugins directory.
          - hello.php
          # This plugin will be loaded from an arbitrary absolute path.
          - /home/plugins/woocommerce/woocommerce.php
          # This plugin will be loaded from an arbitrary relative path inside the project root folder.
          - vendor/acme/project/plugin.php
          # This plugin will be loaded from the project root folder.
          - my-plugin.php
        theme: twentytwentythree # Load the theme from the WordPress installation themes directory.
```

--------------------------------

### WPFilesystem module configuration example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPFilesystem.md

Example configuration for the WPFilesystem module, specifying the required wpRootFolder and optional paths for themes, plugins, mu-plugins, and uploads directories.

```yaml
modules:
  enabled:
    lucatume\WPBrowser\Module\WPFilesystem:
      wpRootFolder: /var/wordpress
      themes: wp-content/themes
      plugins: wp-content/plugins
      mu-plugins: wp-content/mu-plugins
      uploads: wp-content/uploads
```

--------------------------------

### Commands to install dependencies, rebuild WordPress, and run tests

Source: https://github.com/lucatume/wp-browser/blob/master/docs/default-configuration.md

Sequence of commands for a fresh clone or CI runner: install Composer dependencies, rebuild the tests/_wordpress installation with dev:rebuild, install the matching Chromedriver, and run the test suite. The dev:rebuild command downloads WordPress, configures SQLite, and installs it in tests/_wordpress.

```bash
composer install
vendor/bin/codecept dev:rebuild
vendor/bin/codecept chromedriver:update
vendor/bin/codecept run
```

--------------------------------

### assertQueriesCountByStatement example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that exactly 1 query starting with 'INSERT' was made. Queries generated by setUp, tearDown, and factory methods are excluded by default.

```php
<?php
$bookRepository = new Acme\BookRepository();
$repository->where('ID', 23)->set('title', 'Peter Pan', $deferred = true);
$repository->where('ID', 89)->set('title', 'Moby-dick', $deferred = true);
$repository->where('ID', 2389)->set('title', 'The call of the wild', $deferred = false);
$this->assertQueriesCountByStatement(1, 'INSERT', 'Deferred write should happen on __destruct');
```

--------------------------------

### getInstallation()

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPLoader.md

Returns the WordPress installation object.

```APIDOC
## getInstallation()

### Description
Returns the WordPress installation object.

### Method
getInstallation()

### Signature
`getInstallation()` : `lucatume\WPBrowser\WordPress\Installation`

### Parameters
None

### Return Value
- **lucatume\WPBrowser\WordPress\Installation** - The installation object.

```

--------------------------------

### addFunction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

Shows how to add global and namespaced functions using the addFunction method. The example adds two functions and asserts their return values.

```php
<?php

use lucatume\WPBrowser\Traits\UopzFunctions;
use lucatume\WPBrowser\TestCase\WPTestCase;

class MyTest extends WPTestCase
{
    use UopzFunctions;

    public function test_can_add_function()
    {
        $this->addFunction('myGlobalFunction', fn() => 23);
        $this->addFunction('Acme\Project\namespacedFunction', fn() => 89);

        $this->assertEquals(23, myGlobalFunction());
        $this->assertEquals(89, Acme\Project\namespacedFunction());
    }
}
```

--------------------------------

### Configure BuiltInServerController for all suites

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/BuiltInServerController.md

Example configuration that starts the PHP built-in server for all suites. The `docroot` parameter is required and can be an absolute path or relative to the Codeception root directory. The `workers` parameter is optional and defaults to 5; it is ignored on Windows.

```yaml
extensions:
  enabled:
    - "lucatume\\WPBrowser\\Extension\\BuiltInServerController"
  config:
    "lucatume\\WPBrowser\\Extension\\BuiltInServerController":
      docroot: /var/www/html
      workers: 5

```

--------------------------------

### Symlinker configuration with plugins and themes

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/Symlinker.md

Example configuration for the Symlinker extension, linking plugins and themes to the WordPress installation directories. Requires the `wpRootFolder` parameter; `plugins` and `themes` are optional lists of directories. Relative paths are resolved from the current working directory.

```yaml
extensions:
  enabled:
    - "lucatume\\WPBrowser\\Extension\\Symlinker"
  config:
    "lucatume\\WPBrowser\\Extension\\Symlinker":
      wpRootFolder: /var/www/html
      plugins:
        - '.' # Relative path, the current working directory.
        - /home/plugins/plugin-1 # Absolute path to a plugin directory.
        - vendor/acme/plugin-2 # Relative path to a plugin directory.
      themes:
        - /home/theme-1 # Absolute path to a theme directory.
        - vendor/acme/theme-2 # Relative path to a theme directory.
```

--------------------------------

### Configure BuiltInServerController with suites and environment variables

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/BuiltInServerController.md

Example configuration that starts the server only for the specified suites and uses environment variables defined in the tests configuration file. The `suites` parameter is optional; if not set, the server runs for all suites. The `port` parameter defaults to 2389 and `workers` defaults to 5.

```yaml
extensions:
  enabled:
    - "lucatume\\WPBrowser\\Extension\\BuiltInServerController"
  config:
    "lucatume\\WPBrowser\\Extension\\BuiltInServerController":
      suites:
        - EndToEnd
        - WebApp
      docroot: '%WORDPRESS_ROOT_DIR%'
      port: '%BUILT_IN_SERVER_PORT%'
      workers: '%BUILT_IN_SERVER_WORKERS%'

```

--------------------------------

### Linux: Install uopz via pecl

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

Use the pecl command to install the uopz extension on Linux. After installation, verify with php -m.

```bash
pecl install uopz
```

--------------------------------

### assertQueries example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least one query was made during the test. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
wp_cache_delete('page-posts', 'acme');
$pagePosts = $plugin->getPagePosts();
$I->assertQueries('Queries should be made to set the cache.')
```

--------------------------------

### Enable dev:start command

Source: https://github.com/lucatume/wp-browser/blob/master/docs/commands.md

Add this command to the extensions.commands section of your Codeception configuration file to enable the dev:start command.

```yaml
extensions:
  commands:
    - "lucatume\\WPBrowser\\Command\\DevStart"
```

--------------------------------

### Install oscarotero/env via Composer

Source: https://github.com/lucatume/wp-browser/blob/master/tests/_data/fs-templates/bedrock/vendor/oscarotero/env/README.md

Install the package using Composer. Run this command in your project root to add oscarotero/env as a dependency.

```bash
$ composer require oscarotero/env
```

--------------------------------

### GitHub Actions setup for uopz extension

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

YAML configuration to install the uopz extension in a GitHub Actions job using shivammathur/setup-php. Sets PHP 8.1, enables the uopz extension, and sets the ini value uopz.exit=1.

```yaml
- name: Setup PHP 8.1 with uopz
uses: shivammathur/setup-php@v2
with:
  php-version: 8.1
  extensions: uopz
  ini-values: uopz.exit=1
```

--------------------------------

### switchToWindow

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPWebDriver.md

Switches to a window by name. The HTML example creates a window named 'another_window'. The PHP example clicks the button, switches to that window, then switches back to the parent window. If the window has no name, use switchToNextTab or native Selenium functions.

```html
<input type="button" value="Open window" onclick="window.open('https://example.com', 'another_window')">
```

```php
<?php
$I->click("Open window");
# switch to another window
$I->switchToWindow("another_window");
# switch to parent window
$I->switchToWindow();
```

--------------------------------

### WPBrowser module configuration example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Example YAML configuration for the WPBrowser module with static values, setting the site URL, admin credentials, admin path, and custom headers.

```yaml
modules:
  enabled:
    lucatume\WPBrowser\Module\WPBrowser:
      url: 'http://localhost:8080'
      adminUsername: 'admin'
      adminPassword: 'password'
      adminPath: '/wp-admin'
      headers:
        X_WPBROWSER_REQUEST: 1
        X_TEST_REQUEST: 1
        X_APM_REQUEST: 1
```

--------------------------------

### Install PHP_CodeSniffer with PEAR

Source: https://github.com/lucatume/wp-browser/blob/master/tests/_data/fs-templates/bedrock/vendor/squizlabs/php_codesniffer/README.md

Installs PHP_CodeSniffer using the PEAR installer. Requires PEAR to be installed first. After installation, the phpcs and phpcbf commands are immediately available.

```bash
pear install PHP_CodeSniffer
```

--------------------------------

### switchToIframe example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Switches to an iframe or frame on the page. The iframe must have a name attribute. The example shows the HTML and the PHP switch command.

```html
<iframe name="another_frame" src="http://example.com">
```

```php
<?php
# switch to iframe
$I->switchToIframe("another_frame");
```

--------------------------------

### assertQueriesByStatementAndFunction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that queries were made by the specified function starting with the specified SQL statement. Queries generated by setUp, tearDown and factory methods are excluded by default.

```php
<?php
wp_insert_post(['post_type' => 'book', 'post_title' => 'Alice in Wonderland']);
$this->assertQueriesByStatementAndFunction('INSERT', 'wp_insert_post');
```

--------------------------------

### WPLoader configuration with SQLite and database dump

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPLoader.md

Example configuration using a SQLite database and loading database fixtures before tests run. Shows how to specify a dump list, plugins, and a theme with parent from relative path and child from the current working directory.

```yaml
actor: IntegrationTester
bootstrap: _bootstrap.php
modules:
  enabled:
    - \Helper\Integration
    - lucatume\WPBrowser\Module\WPLoader:
        wpRootFolder: /var/wordpress
        dbUrl: sqlite:///var/wordpress/wp-tests.sqlite
        dump:
          - tests/_data/products.sql
          - tests/_data/users.sql
          - tests/_data/orders.sql
        tablePrefix: test_
        domain: wordpress.test
        adminEmail: admin@wordpress.test
        title: 'Integration Tests'
        plugins:
          - hello.php
          - woocommerce/woocommerce.php
          - my-plugin/my-plugin.php
        theme:
          # Parent theme from relative path.
          - vendor/acme/parent-theme
          # Child theme from the current working directory.
          - .
```

--------------------------------

### seePluginInstalled - Assert plugin is installed

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Asserts a plugin is installed regardless of activation status on the plugins administration screen. Does not handle authentication or navigation. Use after logging in and navigating to the plugins page.

```php
<?php
$I->loginAsAdmin();
$I->amOnPluginsPage();
$I->seePluginInstalled('my-plugin');
```

--------------------------------

### grabCookiesWithPattern example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Returns all cookies whose name matches a regex pattern. The example shows logging in, visiting a page, and grabbing cookies matching a pattern.

```php
<?php
$I->loginAs('customer','password');
$I->amOnPage('/shop');
$cartCookies = $I->grabCookiesWithPattern("#^shop_cart\\.*#");
```

--------------------------------

### assertQueriesByStatementAndMethod example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that queries were made by the specified class method starting with the specified SQL statement. Queries generated by setUp, tearDown and factory methods are excluded by default.

```php
<?php
Acme\BookRepository::new(['title' => 'Alice in Wonderland'])->commit();
$this->assertQueriesByStatementAndMethod('UPDATE', Acme\BookRepository::class, 'commit');
```

--------------------------------

### EVENT_BEFORE_INSTALL

Source: https://github.com/lucatume/wp-browser/blob/master/docs/DispatcherAPI.md

Documentation for the EVENT_BEFORE_INSTALL event, including its purpose, usage, and a PHP example.

```APIDOC
## EVENT_BEFORE_INSTALL

### Description
This event fires before WordPress is installed by the `WPLoader` module when `loadOnly` is set to `false`. Due to order-of-operations, you can hook on this event only in the global bootstrap file (usually `tests/_bootstrap.php`).

### Event Name
`WPLoader::EVENT_BEFORE_INSTALL`

### Usage
Register a listener using `Dispatcher::addListener(WPLoader::EVENT_BEFORE_INSTALL, callback)`. The callback receives an `Event` object.

### Callback Parameters
- **$event** (Event) - The event object. Use `$event->getOrigin()` to get the `WPLoader` module instance.

### Notes
- WordPress is not loaded yet, so you cannot use functions or classes defined by WordPress, themes or plugins.
- You can interact with the WordPress installation and use the `lucatume\WPBrowser\WordPress\PreloadFilters` class to hook on actions and filters that will be fired by WordPress once loaded.

### Example
```php
<?php

use lucatume\WPBrowser\Events\Dispatcher;
use lucatume\WPBrowser\Module\WPLoader;
use lucatume\WPBrowser\Events\Event;

Dispatcher::addListener(WPLoader::EVENT_BEFORE_INSTALL, function (Event $event) {
    /** @var WPLoader $wpLoader */
    $wpLoader = $event->getOrigin();
    
    codecept_debug('Running on EVENT_BEFORE_INSTALL');
    
    // Interact with the WordPress installation, its filesystem and database.
    $installation = $wpLoader->getInstallation();
    $pluginsDir = $installation->getPluginsDir();
    $db = $installation->getDb();
    $db->import(codecept_data_dir('some-dump.sql'));
    
    // Use the PreloadFilters class to hook on WordPress actions and filters.
    PreloadFilters::addFilter('init', fn() => update_option('some_option', 'some_value'));
    PreloadFilters::addFilter('pre_option_some_option', fn() => 'some_value');
});
```
```

--------------------------------

### getFunctionStaticVariables example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

Shows how to retrieve the static variable of a function using the getFunctionStaticVariables method. The example defines a renderScreen function with a static $screenHash and asserts the output matches.

```php
<?php

use lucatume\WPBrowser\Traits\UopzFunctions;
use lucatume\WPBrowser\TestCase\WPTestCase;

function renderScreen(): string {
    static $screenHash;

    if(!$screenHash){
        $screenHash = md5(microtime());
    }
    
    return '<p data-screen="' . $screenHash . '">Some HTML</p>';
}

class MyTest extends WPTestCase
{
    use UopzFunctions;

    public function test_can_set_function_static_variables()
    {
        $screenHash = $this->getFunctionStaticVariables('renderScreen')['screenHash'];

        $this->assertEquals('<p data-screen="' . $screenHash . '">Some HTML</p>', renderScreen());
    }
}
```

--------------------------------

### getObjectProperty example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

Gets the value of a static or instance property from an object. The example shows retrieving a private property from a controller object.

```php
<?php

use lucatume\WPBrowser\Traits\UopzFunctions;
use lucatume\WPBrowser\TestCase\WPTestCase;

class LegacyController {
    private Template $template;

    public function __construct(){
        $this->template = new Template();
    }

    // ...
}

class MyTest extends WPTestCase
{
    use UopzFunctions;

    public function test_can_get_object_property()
    {
        $controller = new LegacyController();

        $templateEngine $this->getObjectProperty($controller, 'template'));

        // ... do something with the template ...
    }
}
```

--------------------------------

### haveHttpHeader examples

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Sets an HTTP header for subsequent requests through PhpBrowser. The first example sets a simple header; the second shows how to use HTML character entities for special characters like underscores.

```php
<?php
$I->haveHttpHeader('X-Requested-With', 'Codeception');
$I->amOnPage('test-headers.php');
```

```php
<?php
$I->haveHttpHeader('Client&#95;Id', 'Codeception');
```

--------------------------------

### Install PHP_CodeSniffer with Phive

Source: https://github.com/lucatume/wp-browser/blob/master/tests/_data/fs-templates/bedrock/vendor/squizlabs/php_codesniffer/README.md

Installs PHP_CodeSniffer as a project tool using Phive. After installation, the tools are available in the tools directory.

```bash
phive install phpcs
phive install phpcbf
```

--------------------------------

### Symlinker configuration with environment variables

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/Symlinker.md

Configuration example showing how to use environment variables defined in the tests configuration file. The `wpRootFolder`, `plugins`, and `themes` values can reference environment variables using the `%VAR%` syntax.

```yaml
extensions:
  enabled:
    - "lucatume\\WPBrowser\\Extension\\Symlinker"
  config:
    "lucatume\\WPBrowser\\Extension\\Symlinker":
      wpRootFolder: '%WP_ROOT_FOLDER%'
      plugins:
        - '%PLUGIN_STORAGE%/plugin-1'
        - '%PLUGIN_STORAGE%/plugin-2'
      themes:
        - '%THEME_STORAGE%/theme-1'
        - '%THEME_STORAGE%/theme-2'
```

--------------------------------

### grabBlogTablePrefix - Get table prefix for a blog

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns the table prefix for a blog. The example creates a blog, gets its prefix, and uses it to construct a table name.

```php
<?php
$blogId = $I->haveBlogInDatabase('test');
$blogTablePrefix = $I->getBlogTablePrefix($blogId);
$blogOrders = $I->blogTablePrefix . 'orders';
```

--------------------------------

### Install PHP_CodeSniffer globally with Composer

Source: https://github.com/lucatume/wp-browser/blob/master/tests/_data/fs-templates/bedrock/vendor/squizlabs/php_codesniffer/README.md

Installs PHP_CodeSniffer system-wide using Composer. Requires the composer bin dir to be in your PATH; the default is ~/.composer/vendor/bin/.

```bash
composer global require "squizlabs/php_codesniffer=*"
```

--------------------------------

### useTheme: Set current theme options

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Sets the current theme options. The example shows using a stylesheet, a template, and a theme name.

```php
<?php
$I->useTheme('twentyseventeen');
$I->useTheme('child-of-twentyseventeen', 'twentyseventeen');
$I->useTheme('acme', 'acme', 'Acme Theme');
```

--------------------------------

### amOnCronPage

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Goes to the cron page to start a synchronous, blocking GET request to the cron script.

```APIDOC
## amOnCronPage

### Description
Go to the cron page to start a synchronous, and blocking, `GET` request to the cron script.

### Method
amOnCronPage

### Signature
`amOnCronPage([array|string|null $queryVars])` : `void`

### Parameters
- **$queryVars** (array|string|null) - Optional - Query variables to append to the URL.

### Example
```php
<?php
// Triggers the cron job with an optional query argument.
$I->amOnCronPage('/?some-query-var=some-value');
```
```

--------------------------------

### Hook EVENT_AFTER_INSTALL with Dispatcher::addListener

Source: https://github.com/lucatume/wp-browser/blob/master/docs/DispatcherAPI.md

Fires after WordPress is installed by WPLoader when loadOnly is false. Hook only in the global bootstrap file (usually tests/_bootstrap.php). Use to interact with the WordPress installation, filesystem, and database before dump files are imported.

```php
<?php

use lucatume\WPBrowser\Events\Dispatcher;
use lucatume\WPBrowser\Module\WPLoader;
use lucatume\WPBrowser\Events\Event;

Dispatcher::addListener(WPLoader::EVENT_AFTER_INSTALL, function (Event $event) {
    /** @var WPLoader $wpLoader */
    $wpLoader = $event->getOrigin();
    
    codecept_debug('Running on EVENT_AFTER_INSTALL');
           
    // Interact with the WordPress installation, its filesystem and database.    
    $installation = $wpLoader->getInstallation();
    $pluginsDir = $installation->getPluginsDir();
    $db = $installation->getDb();
    $db->import(codecept_data_dir('some-dump.sql'));
    
    // Use WordPress functions and classes.    
    update_option('some_option', 'some_value');
});
```

--------------------------------

### amOnAdminAjaxPage - Start admin AJAX request

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Goes to admin-ajax.php to start a synchronous GET AJAX request. Does not handle authentication, nonces, or authorization. Accepts optional query variables as an array or string.

```php
<?php
$I->amOnAdminAjaxPage(['action' => 'my-action', 'data' => ['id' => 23], 'nonce' => $nonce]);
```

--------------------------------

### Run PHP_CodeSniffer from tools directory after Phive install

Source: https://github.com/lucatume/wp-browser/blob/master/tests/_data/fs-templates/bedrock/vendor/squizlabs/php_codesniffer/README.md

Verifies the Phive installation by running the phpcs and phpcbf commands from the tools directory.

```bash
./tools/phpcs -h
./tools/phpcbf -h
```

--------------------------------

### WPFilesystem module configuration with dynamic parameters

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPFilesystem.md

Configuration using dynamic configuration parameters to set the wpRootFolder value.

```yaml
modules:
  enabled:
    lucatume\WPBrowser\Module\WPFilesystem:
      wpRootFolder: '%WP_ROOT_FOLDER%'
```

--------------------------------

### grabLatestEntryByFromDatabase - Get last entry ID

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns the id value of the last table entry. The example creates multiple posts, gets the posts table name, and retrieves the latest entry ID.

```php
<?php
$I->haveManyPostsInDatabase();
$postsTable = $I->grabPostsTableName();
$last = $I->grabLatestEntryByFromDatabase($postsTable, 'ID');
```

--------------------------------

### grabUserMetaFromDatabase

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Gets a user meta from the database. The example shows retrieving a karma value and an unserialized array value.

```php
<?php
// Returns a user 'karma' value.
$I->grabUserMetaFromDatabase($userId, 'karma');
// Returns an array, the unserialized version of the value stored in the database.
$I->grabUserMetaFromDatabase($userId, 'api_data');
```

--------------------------------

### Example .gitignore for wp-browser project

Source: https://github.com/lucatume/wp-browser/blob/master/docs/default-configuration.md

Shows the recommended .gitignore entry to exclude the vendor directory. The tests/_wordpress directory is already ignored by a generated .gitignore, and other rebuildable directories should be ignored as usual.

```gitignore
# .gitignore
/vendor/
```

--------------------------------

### seeAttachmentInDatabase: Check for attachment in database

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Checks for an attachment in the database. The example checks for an attachment with a specific GUID URL.

```php
<?php
$url = 'https://example.org/images/foo.png';
$I->seeAttachmentInDatabase(['guid' => $url]);
```

--------------------------------

### dontSeeAttachmentInDatabase - Check attachment not in database

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Checks that an attachment is not in the database. Example checks that an attachment with a specific GUID is absent.

```php
<?php
$url = 'https://example.org/images/foo.png';
$I->dontSeeAttachmentInDatabase(['guid' => $url]);
```

--------------------------------

### Initialize wp-browser with Codeception

Source: https://github.com/lucatume/wp-browser/blob/master/docs/README.md

Initializes wp-browser with a default configuration that sets up integration and end-to-end tests using SQLite, PHP's built-in web server, and Chromedriver. For plugin or theme projects, it also installs WordPress and creates symlinked directories for plugins and themes.

```bash
vendor/bin/codecept init wpbrowser
```

--------------------------------

### grabTermsTableName

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Gets the prefixed terms table name (e.g., `wp_terms`). The example shows the default and after switching to blog 23.

```php
<?php
// Returns 'wp_terms'.
$I->grabTermsTableName();
// Returns 'wp_23_terms'.
$I->useBlog(23);
$I->grabTermsTableName();
```

--------------------------------

### logOut examples

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Navigates to the default WordPress logout page and clicks the logout link. Three examples show different redirect behaviors: returning to the current page, remaining on the logout page, or moving to another page.

```php
<?php
// Log out using the `wp-login.php` form and return to the current page.
$I->logOut(true);
// Log out using the `wp-login.php` form and remain there.
$I->logOut(false);
// Log out using the `wp-login.php` form and move to another page.
$I->logOut('/some-other-page');
```

--------------------------------

### amOnAdminAjaxPage

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Goes to the admin-ajax.php page to start a synchronous, blocking GET AJAX request. Does not handle authentication, nonces, or authorization.

```APIDOC
## amOnAdminAjaxPage

### Description
Go to the `admin-ajax.php` page to start a synchronous, and blocking, `GET` AJAX request. The method will **not** handle authentication, nonces or authorization.

### Method
amOnAdminAjaxPage

### Signature
`amOnAdminAjaxPage([array|string|null $queryVars])` : `void`

### Parameters
- **$queryVars** (array|string|null) - Optional - Query variables to append to the URL.

### Example
```php
<?php
$I->amOnAdminAjaxPage(['action' => 'my-action', 'data' => ['id' => 23], 'nonce' => $nonce]);
```
```

--------------------------------

### grabBlogPath - Grab blog path and navigate

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Grabs a blog domain (likely meant path) and uses it to navigate. Example creates a blog, grabs its domain, and visits the root.

```php
<?php
$blogId = $I->haveBlogInDatabase('test');
$path = $I->grabBlogDomain($blogId);
$I->amOnSubdomain($path);
$I->amOnPage('/');
```

--------------------------------

### assertQueriesByFunction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that queries were made by the acme_clean_queue function. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
acme_clean_queue();
$this->assertQueriesByFunction('acme_clean_queue');
```

--------------------------------

### MySqlServerController configuration with environment variables

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/MySqlServerController.md

Example configuration using environment variables defined in the tests configuration file. The extension can access these variables to set the port, database, user, and password.

```yaml
extensions:
  enabled:
    - "lucatume\WPBrowser\Extension\MySqlServerController":
      port: '%MYSQL_SERVER_PORT%'
      database: '%MYSQL_SERVER_DATABASE%'
      user: '%MYSQL_SERVER_USER%'
      password: '%MYSQL_SERVER_PASSWORD%'
```

--------------------------------

### seeTableInDatabase: Check table exists

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Checks that a table is in the database. The example uses grabPrefixedTableNameFor to get the prefixed table name for 'options'.

```php
<?php
$options = $I->grabPrefixedTableNameFor('options');
$I->seeTableInDatabase($options);
```

--------------------------------

### grabTermTaxonomyTableName

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Gets the prefixed term and taxonomy table name (e.g., `wp_term_taxonomy`). The example shows the default and after switching to blog 23.

```php
<?php
// Returns 'wp_term_taxonomy'.
$I->grabTermTaxonomyTableName();
// Returns 'wp_23_term_taxonomy'.
$I->useBlog(23);
$I->grabTermTaxonomyTableName();
```

--------------------------------

### Hook EVENT_BEFORE_INSTALL with Dispatcher

Source: https://github.com/lucatume/wp-browser/blob/master/docs/DispatcherAPI.md

Registers a listener for the WPLoader::EVENT_BEFORE_INSTALL event. Use this in the global bootstrap file (e.g., tests/_bootstrap.php) to run code before WordPress is installed when loadOnly is false. WordPress is not loaded yet, so only PreloadFilters can be used to hook actions/filters.

```php
<?php

use lucatume\WPBrowser\Events\Dispatcher;
use lucatume\WPBrowser\Module\WPLoader;
use lucatume\WPBrowser\Events\Event;

Dispatcher::addListener(WPLoader::EVENT_BEFORE_INSTALL, function (Event $event) {
    /** @var WPLoader $wpLoader */
    $wpLoader = $event->getOrigin();
    
    codecept_debug('Running on EVENT_BEFORE_INSTALL');
    
    // Interact with the WordPress installation, its filesystem and database.
    $installation = $wpLoader->getInstallation();
    $pluginsDir = $installation->getPluginsDir();
    $db = $installation->getDb();
    $db->import(codecept_data_dir('some-dump.sql'));
    
    // Use the PreloadFilters class to hook on WordPress actions and filters.
    PreloadFilters::addFilter('init', fn() => update_option('some_option', 'some_value'));
    PreloadFilters::addFilter('pre_option_some_option', fn() => 'some_value');
});
```

--------------------------------

### grabTermMetaTableName

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Gets the prefixed term meta table name (e.g., `wp_termmeta`). The example shows the default and after switching to blog 23.

```php
<?php
// Returns 'wp_termmeta'.
$I->grabTermMetaTableName();
// Returns 'wp_23_termmeta'.
$I->useBlog(23);
$I->grabTermMetaTableName();
```

--------------------------------

### MySqlServerController configuration with custom binary

Source: https://github.com/lucatume/wp-browser/blob/master/docs/extensions/MySqlServerController.md

Example configuration using a custom MySQL server binary. The `binary` parameter must be the absolute path to the binary, and `shareDir` is required when providing a custom binary.

```yaml
extensions:
  enabled:
    - "lucatume\WPBrowser\Extension\MySqlServerController":
      port: 33446
      database: wordpress
      user: root
      password: secret
      binary: /usr/local/mysql/bin/mysqld
```

--------------------------------

### assertQueriesCountByFunction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that n queries were made by the specified function. Queries generated by setUp, tearDown and factory methods are excluded by default.

```php
<?php
$this->assertCount(3, Acme\get_orphaned_posts());
Acme\delete_orphaned_posts();
$this->assertQueriesCountByFunction(3, 'Acme\delete_orphaned_posts');
```

--------------------------------

### assertQueriesByStatement

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least a query starting with the specified statement was made. Queries generated by setUp, tearDown and factory methods are excluded by default.

```APIDOC
## assertQueriesByStatement

### Description
Asserts that at least a query starting with the specified statement was made. Queries generated by `setUp`, `tearDown` and `factory` methods are excluded by default.

### Signature
`assertQueriesByStatement(string $statement, [string $message]) : void`

### Parameters
- **$statement** (string) - Required - The SQL statement to check (e.g., 'SELECT').
- **$message** (string) - Optional - A custom assertion message.

### Example
```php
<?php
wp_cache_flush();
cached_get_posts($args);
$I->assertQueriesByStatement('SELECT');
```
```

--------------------------------

### cli

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPCLI.md

Executes a wp-cli command targeting the test WordPress installation.

```APIDOC
## cli([array|string $command], [?array $env], [mixed $input]) : int

### Description
Executes a wp-cli command targeting the test WordPress installation.

### Method
cli

### Parameters
- **$command** (array|string) - Required - The command to execute, either as an array of arguments or a string.
- **$env** (?array) - Optional - Environment variables for the command.
- **$input** (mixed) - Optional - Input to pass to the command.

### Request Example
```php
<?php
// Activate a plugin via wp-cli in the test WordPress site.
$I->cli(['plugin', 'activate', 'my-plugin']);
// Change a user password.
$I->cli(['user', 'update', 'luca', '--user_pass=newpassword']);
```
```

--------------------------------

### assertQueriesByStatementAndMethod example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that the commit method of Acme\BookRepository made an INSERT query. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
Acme\BookRepository::new(['title' => 'Alice in Wonderland'])->commit();
$this->assertQueriesByStatementAndMethod('INSERT', Acme\BookRepository::class, 'commit');
```

--------------------------------

### WPBrowser module configuration with dynamic parameters

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Example YAML configuration using dynamic configuration parameters (e.g., %WORDPRESS_URL%) to set the module settings, including custom headers.

```yaml
modules:
  enabled:
    lucatume\WPBrowser\Module\WPBrowser:
      url: '%WORDPRESS_URL%'
      adminUsername: '%WORDPRESS_ADMIN_USER%'
      adminPassword: '%WORDPRESS_ADMIN_PASSWORD%'
      adminPath: '/wp-admin'
      headers:
        X_WPBROWSER_REQUEST: 1
        X_TEST_REQUEST: 1
        X_APM_REQUEST: 1
```

--------------------------------

### assertNotQueriesByStatementAndFilter example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that no queries were made by the 'the_title' filter with a SELECT statement. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
add_filter('the_title', function($title, $postId){
     $post = get_post($postId);
     if($post->post_type !== 'book'){
         return $title;
     }
     $new = get_option('acme_new_prefix');
     return "{$new} - " . $title;
});
$title = apply_filters('the_title', get_post($notABookId)->post_title, $notABookId);
$this->assertNotQueriesByStatementAndFilter('SELECT', 'the_title');
```

--------------------------------

### openFile and seeInThisFile: Open a file and check its content

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPFilesystem.md

Opens a file and stores its content for subsequent assertions. The example opens composer.json and checks it contains 'codeception/codeception'.

```php
<?php
$I->openFile('composer.json');
$I->seeInThisFile('codeception/codeception');
```

--------------------------------

### grabCommentsTableName - Get comments table name

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns the comments table name, with prefix. The example shows the table name before and after switching to blog 23.

```php
<?php
// Will be `wp_comments`.
$comments = $I->grabCommentsTableName();
// Will be `wp_23_comments`.
$I->useBlog(23);
$comments = $I->grabCommentsTableName();
```

--------------------------------

### grabAllFromDatabase - Grab all matching entries from a table

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns all entries matching criteria from a database table. Example uses grabPrefixedTableNameFor to get the table name.

```php
<?php
$books = $I->grabPrefixedTableNameFor('books');
$I->grabAllFromDatabase($books, 'title', ['genre' => 'fiction']);
```

--------------------------------

### WPDb module configuration with dynamic parameters

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Example YAML configuration for the WPDb module using dynamic configuration parameters (e.g., %DB_URL%, %WORDPRESS_URL%). This allows values to be injected at runtime. The structure mirrors the MySQL example but uses placeholders for all configurable values.

```yaml
modules:
  enabled:
    - lucatume\WPBrowser\Module\WPDb:
        dbUrl: '%DB_URL%'
        url: '%WORDPRESS_URL%'
        tablePrefix: '%WORDPRESS_TABLE_PREFIX%'
        dump: '%DB_DUMP%'
        populate: true
        cleanup: true
        reconnect: false
        urlReplacement: true
        originalUrl: '%WORDPRESS_ORIGINAL_URL%'
        waitlock: 10
        createIfNotExists: true
```

--------------------------------

### assertQueriesCountByFilter example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that n queries were made as a consequence of the specified filter. Queries generated by setUp, tearDown and factory methods are excluded by default.

```php
<?php
add_filter('the_title', function($title, $postId){
     $post = get_post($postId);
     if($post->post_type !== 'book'){
         return $title;
     }
     $new = get_option('acme_new_prefix');
     return "{$new} - " . $title;
});
$title = apply_filters('the_title', get_post($bookOneId)->post_title, $bookOneId);
$title = apply_filters('the_title', get_post($notABookId)->post_title, $notABookId);
$title = apply_filters('the_title', get_post($bookTwoId)->post_title, $bookTwoId);
$this->assertQueriesCountByFilter(2, 'the_title');
```

--------------------------------

### assertQueriesCountByAction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that n queries were made as a consequence of the specified action. Queries generated by setUp, tearDown and factory methods are excluded by default.

```php
<?php
add_action( 'edit_post', function($postId){
        $count = get_option('acme_title_updates_count');
        update_option('acme_title_updates_count', ++$count);
} );
wp_update_post(['ID' => $bookOneId, 'post_title' => 'One']);
wp_update_post(['ID' => $bookTwoId, 'post_title' => 'Two']);
wp_update_post(['ID' => $bookThreeId, 'post_title' => 'Three']);
$this->assertQueriesCountByAction(3, 'edit_post');
```

--------------------------------

### writeToThemeFile example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPFilesystem.md

Writes a string to a file in a theme folder. The file path is relative to the themes directory.

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

--------------------------------

### assertQueriesByMethod example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least one query was made by the update method of Acme\Options. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
$options = new Acme\Options();
$options->update('showAds', false);
$I->assertQueriesByMethod('Acme\Options', 'update');
```

--------------------------------

### executeInGuzzle example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Low-level API method to use Guzzle HTTP Client directly when Codeception commands are insufficient. Not recommended for regular use; consider submitting patches for missing Guzzle methods.

```php
<?php
$I->executeInGuzzle(function (\GuzzleHttp\Client $client) {
     $client->get('/get', ['query' => ['foo' => 'bar']]);
});
```

--------------------------------

### assertQueriesByFilter example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least one query was made as a consequence of the 'the_title' filter. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
add_filter('the_title', function($title, $postId){
     $post = get_post($postId);
     if($post->post_type !== 'book'){
         return $title;
     }
     $new = get_option('acme_new_prefix');
     return "{$new} - " . $title;
});
$title = apply_filters('the_title', get_post($bookId)->post_title, $bookId);
$this->assertQueriesByFilter('the_title');
```

--------------------------------

### assertQueriesByAction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that at least one query was made as a consequence of the 'edit_post' action. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
add_action( 'edit_post', function($postId){
        $count = get_option('acme_title_updates_count');
        update_option('acme_title_updates_count', ++$count);
} );
wp_update_post(['ID' => $bookId, 'post_title' => 'New Title']);
$this->assertQueriesByAction('edit_post');
```

--------------------------------

### startFollowingRedirects example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPBrowser.md

Enables automatic redirect following. Use when you need the client to follow redirects automatically.

```php
<?php
$I->startFollowingRedirects();
```

--------------------------------

### Windows: Locate php.ini with php --ini

Source: https://github.com/lucatume/wp-browser/blob/master/docs/traits/UopzFunctions.md

Run this command to locate the php.ini file on Windows, which is the first step in installing the uopz extension locally.

```powershell
php --ini
```

--------------------------------

### assertNotQueriesByStatementAndFunction example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPQueries.md

Asserts that no INSERT queries were made by wp_insert_post, but UPDATE queries were made. Queries from setUp, tearDown, and factory methods are excluded by default.

```php
<?php
wp_insert_post(['ID' => $bookId, 'post_title' => 'The Call of the Wild']);
$this->assertNotQueriesByStatementAndFunction('INSERT', 'wp_insert_post');
$this->assertQueriesByStatementAndFunction('UPDATE', 'wp_insert_post');
```

--------------------------------

### grabBlogTableName - Grab prefixed blog table name

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns the full table name for a blog in a multisite installation. Example grabs the 'option' table for a blog.

```php
<?php
$blogOptionTable = $I->grabBlogTableName($blogId, 'option');
```

--------------------------------

### grabLinksTableName - Get prefixed links table name

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Returns the prefixed links table name. The example shows the table name before and after switching to blog 23.

```php
<?php
// Given a `wp_` table prefix returns `wp_links`.
$linksTable = $I->grabLinksTableName();
// Given a `wp_` table prefix returns `wp_23_links`.
$I->useBlog(23);
$linksTable = $I->grabLinksTableName();
```

--------------------------------

### grabSiteOptionFromDatabase

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPDb.md

Retrieves a site option from the database. The example shows inserting a site option and then retrieving it.

```php
<?php
$fooCountOptionId = $I->haveSiteOptionInDatabase('foo_count','23');
```

--------------------------------

### writeToMuPluginFile example

Source: https://github.com/lucatume/wp-browser/blob/master/docs/modules/WPFilesystem.md

Writes a file in a mu-plugin folder. The file path is relative to the mu-plugins directory.

```php
$I->writeToMuPluginFile('mu-plugin1/some-file.txt', 'foo');
```
Tokens:
Raw