DOCSEARCHbyAlgolia
Submit Docs

wp-browser Documentation

repository·master·Indexed 20 days ago

https://github.com/lucatume/wp-browser

A testing tool for WordPress sites, plugins, and themes that facilitates end-to-end, integration, and unit tests using Codeception, SQLite, and a built-in PHP web server. It includes specialized test case generators, database import/export commands for SQLite and MySQL, and 'Airplane Mode' to control external file loading during local development.

Tokens
113.5K
Snippets
418
Records
488
Agent score
71%

What's inside wp-browser

  1. What is Airplane Mode and when to use it

    master

    Airplane Mode is a tool designed to control the loading of external files during local WordPress development. It is particularly useful when working in environments without a web connection.

    By removing or unhooking specific actions, it reduces load times and prevents errors that occur when WordPress attempts to fetch external resources (like fonts or Gravatars) that are unreachable.

    Key features include:

    • Removing external JS and CSS files from loading.
    • Replacing Gravatar instances with a local image to eliminate external HTTP calls.
    • Removing all HTTP requests.
    • Disabling WordPress update checks for core, languages, themes, and plugins.
    • Providing an admin bar toggle for quick enabling and disabling.

  2. What is the WPFilesystem module and when to use it?

    master

    The WPFilesystem module is designed for acceptance and functional testing. It provides a way to interact with the WordPress filesystem directly, bypassing WordPress methods, functions, or filters. This is useful for low-level filesystem assertions or setup.

    Key capabilities include:

    • Reading, writing, and updating files directly.
    • Scaffolding plugins and themes on the fly during tests.
    • Automatic removal of scaffolded plugins and themes after each test.

  3. What is the WPBrowser module?

    master

    The WPBrowser module allows you to browse and test a WordPress site's HTML using a fast browser that does not support JavaScript. It is an extension of the Codeception PHPBrowser module.

    It is optimized for speed and stability and is ideal for testing scenarios that do not require JavaScript execution, such as:

    • Verifying HTTP return codes.
    • Asserting HTML structure.
    • Testing JSON and XML responses from APIs.

    For full site control, WPBrowser is typically used in conjunction with the WPDb module (to control the database) and the WPFilesystem module (to control the file structure).

  4. Use the WPBrowser module for WordPress testing

    master

    The WPBrowser module is designed for acceptance and functional tests. It extends the PHPBrowser module by adding WordPress-specific configuration and methods.

    Important Limitations:

    • It simulates user interaction without Javascript support.
    • If your tests require Javascript support, use the WPWebDriver module instead.

  6. Use the WpWebDriver module for acceptance tests

    master

    The WpWebDriver module is designed for acceptance testing and extends the standard Codeception WebDriver module. It adds WordPress-specific configuration parameters and methods.

    Key distinction: Use WpWebDriver when you need Javascript support to simulate user interactions. If you do not require Javascript support, use the WPBrowser module instead.

  7. Use the WPLoader module for WordPress testing (v3)

    master

    The WPLoader module is used to bootstrap WordPress in the context of your tests. It is a wrapper around the WordPress PHPUnit Core test suite.

    Use Cases

    • Integration Tests: Use WPLoader to bootstrap WordPress code. By default, all database changes are wrapped in a transaction and rolled back after each test method to ensure test independence and performance. Note that because of this, inspecting the database via XDebug during integration tests will not show any changes.
    • Acceptance and Functional Tests: Set the loadOnly parameter to true. In this mode, WordPress is loaded without a fresh installation, and database operations are committed (not rolled back).

    Important Constraint

    To take full advantage of the suite and ensure proper database handling, you must use the WP_UnitTestCase test case class. Using other test case classes will likely result in errors if a test defines more than one test method.

    modules:
    enabled:
        - WPLoader
    config:
        WPLoader:
            wpRootFolder: "/path/to/wordpress"
            dbName: "test_db"
            dbHost: "localhost"
            dbUser: "root"
            dbPassword: "password"

  8. Use the AirplaneMode module to prevent network requests

    master

    The AirplaneMode module puts the WordPress website under test into "airplane mode," which prevents the site from making any outbound network requests. This is achieved by adding or removing the norcross/airplane-mode plugin to the WordPress must-use (mu-plugins) directory during the test lifecycle.

    This module is designed to be used in conjunction with either the WPWebDriver or WPBrowser modules.

  9. Manage global and static attribute backups in WPLoader

    master

    To prevent test failures caused by plugins or themes that define classes which cannot be serialized, you can disable global or static attribute backups, or exclude specific items from the backup process.

    Disable backups entirely

    Set backupGlobals: false and backupStaticAttributes: false in your configuration.

    Exclude specific items

    Use backupGlobalsExcludeList for variables and backupStaticAttributesExcludeList for class methods.

    Note: A test case explicitly setting the backupGlobals or backupStaticAttributes property will override the module configuration.

    modules:
  enabled:
    - lucatume\WPBrowser\Module\WPLoader:
        backupGlobals: false
        backupStaticAttributes: false
        backupGlobalsExcludeList:
          - my_plugin_will_explode_on_wakeup
          - another_problematic_global
        backupStaticAttributesExcludeList:
          - MyPlugin\MyClass:
              - instance
              - anotherStaticAttributeThatWillExplodeOnWakeup
          - AnotherPlugin\AnotherClass:
              - instance
              - yetAnotherStaticAttributeThatWillExplodeOnWakeup

  10. What the WPDb module is and when to use it

    master

    The WPDb module allows you to manipulate the WordPress database directly without using the WordPress API. It is designed for end-to-end testing and should be used within Cest and Cept test cases.

    Important Usage Guidelines:

    • Use with: WPBrowser, WPWebDriver, and WPFilesystem modules to control site state, database, and file structure.
    • Avoid mixing with WPLoader: Do not use WPDb and WPLoader together to control database state or set up fixtures.
      • Use WPDb for end-to-end testing.
      • Use WPLoader for integration testing.
    • If you need to load a database dump for integration tests, use the dump configuration parameter within the WPLoader module instead of using WPDb.

  11. Understand the WPWebDriver module

    master

    The WPWebDriver module simulates user interactions with a WordPress project by driving a browser via solutions like Selenium or Chromedriver.

    Unlike the standard WPBrowser module, WPWebDriver provides full JavaScript support. This makes it suitable for:

    • Testing sites that rely on JavaScript for page rendering.
    • Performing assertions that require JavaScript execution.

    It extends the Codeception WebDriver module and is intended for use within Cest and Cept test cases.

  12. Use the WPCLI module for testing

    master

    The WPCLI module is used in acceptance and functional tests to set up or verify test pre- and post-conditions using WP-CLI commands.

    Important Note: The module uses its own internal version of WP-CLI, not the one installed on your local machine. By default, it only includes the wp-cli/wp-cli package, which contains basic files but lacks the full suite of standard WP-CLI commands (like wp plugin or wp theme).