Code contributions, bug reports, and feature requests are welcome! The following document provides information about development processes and testing.
Tip
To learn more about contributing to the project, please read our Code of Conduct and Contributing Guidelines guidelines.
The plugin is organized as follows:
Click to expand
snapwp-helper/
│
│ # The built assets, compiled via `npm run build:dist`. They are excluded from the repository and should not be edited directly.
├── build/
│
│ # The Frontend assets, including JavaScript, CSS, and images.
│ # Each package has its own directory, which is mapped in `webpack.config.js`.
├── packages/
│ └── admin/ # Runs on our plugin's admin pages.
│
│ # PHP classes and functions.
│ # Classes follow PSR-4, and are namespaced at `SnapWP\Helper`.
├── src/
│ ├── Interfaces/ # PHP interfaces.
│ │
│ │ # Individual features exist as co-located "Modules".
│ ├── Modules/
│ │ ├── Admin.php # Registers the plugin's admin pages.
│ │ ├── Assets.php # Registers WP scripts and styles.
│ │ │
│ │ │ # Manages WPGraphQL functionality
│ │ ├── GraphQL/
│ │ │ ├── Interfaces/ # Local PHP interfaces for the Module.
│ │ │ ├── Model/ # Custom WPGraphQL Models
│ │ │ ├── Type/ # Custom WPGraphQL types
│ │ │ │
│ │ │ ├── SchemaFilters.php # Modifies existing WPGraphQL schema.
│ │ │ └── TypeRegistry.php # Registers custom WPGraphQL types.
│ │ │
│ │ └── PluginUpdater/ # Plugin Updater Module
│ │ └── UpdateChecker.php # Update Checker API
│ │
│ ├── Traits/ # Reusable PHP traits.
│ │
│ ├── Utils/ # Utility methods
│ │
│ ├── Autoloader.php # The PSR-4 autoloader for the plugin.
│ ├── Dependencies.php # Manages plugin dependencies (e.g. WPGraphQL versions).
│ └── Main.php # The main plugin class.
│
├── tests/ # Test files.
├── vendor/ # Composer dependencies
│
│ # Important root files.
├── access-functions.php # Globally-available functions. External code should use these functions to access plugin functionality instead of directly calling individual class methods.
├── activation.php # Runs when the plugin is activated.
└── snapwp-helper.php # Main plugin file
To test or build the plugin locally, you must clone the plugin from GitHub. Downloading from Composer, WordPress.org, or Packagist will not include the necessary development files.
To use the Docker-ized test environment and to run the tests, you will also need:
- Docker running Docker Compose v2.20 or higher.
# Clone the repository
git clone
# Switch to the plugin directory
cd snapwp-helper
# Copy the .env.dist file to .env
# Make Sure to Update the .env file with the correct values
cp .env.dist .env
# Install the test environment
npm run install-test-env
### Commands
# Run lints
npm run lint:php
npm run lint:php:fix
npm run lint:phpstan
# Run Codeception tests
vendor/bin/codecept run <suite-name>
XDEBUG_MODE=coverage vendor/bin/codecept run <suite-name> --coverage --coverage-html
# Run Playwright tests
npm run test:e2e
npm run test:e2e:ui
# Build the plugin for production and generate a .zip file
npm run build:dist
npm run plugin-zipFor the plugin to work locally, you need to install both the NPM and Composer dependencies, and then build the Assets.
npm run install-local-depsThis command will install the NPM and Composer dependencies and build the assets.
To run the tests, you will need a local WordPress environment. You can use any of the following methods.
-
Install the Plugin dependencies.
-
Copy the
.env.distfile to.envand update the values to match your local WordPress environment.Note: If you are using LocalWP, make sure the
.envvalues match the internal values used inside the container. -
Set up the testing environment by running the following command:
npm run install-test-env. This command will:- Download the latest version of WordPress (if not already downloaded).
- Reset the database and install WordPress.
- Install and activate the necessary plugins.
- Symbolically link the plugin to the WordPress plugins directory.
- Install the Composer and NPM dependencies for the plugin.
-
Copy the
./.docker/.env.cifile to the root of the plugin and rename to.env. -
Build and spin up the docker image.
npm run docker:start
-
Initialize the docker test environment inside of docker.
docker exec -e COVERAGE=1 $(docker compose ps -q wordpress) init-docker.sh
To build the plugin for production, run the following command:
npm run build:distThis will clean up the dev-dependencies and build the assets.
You can then generate the production .zip file by with the following command:
npm run plugin-zip
The develop branch is used for active development, while main contains a snapshot the current stable release. Always create a new branch from develop when working on a new feature or bug fix.
Branches should be prefixed with the type of change (e.g. feat, chore, tests, fix, etc.) followed by a short description of the change. For example, a branch for a new feature called "Add new feature" could be named feat/add-new-feature.
This project uses several tools to ensure code quality and standards are maintained:
This project uses PHP_CodeSniffer to enforce WordPress Coding Standards. We use the WPGraphQL Coding Standards ruleset, which is a superset of WPCS, VIPCS, and Slevomat Coding Standard tailored for the WPGraphQL ecosystem.
Our specific ruleset is defined in the phpcs.xml.dist file.
You can run the PHP_CodeSniffer checks using the following command:
npm run lint:phpPHP_CodeSniffer can automatically fix some issues. To fix issues automatically, run:
npm run lint:php:fixThis project uses PHPStan to perform static analysis on the PHP code. PHPStan is a PHP Static Analysis Tool that focuses on finding errors in your code without actually running it.
You can run PHPStan using the following command:
npm run lint:phpstanThis project uses ESLint through @wordpress/scripts and @wordpress/eslint-plugin for JavaScript linting, following WordPress coding standards and best practices.
You can run ESLint on JavaScript files using:
npm run lint:jsTo automatically fix JavaScript linting issues:
npm run lint:js:fixYou can also generate a detailed JSON report of linting issues:
npm run lint:js:reportThis project uses the wp-browser library for Codeception to run PHP unit, integration, and acceptance tests.
Tests are located in the tests/ directory, with a separate directory for each test suite corresponding to its *.suite.dist.yml configuration file.
Note
Codeception Acceptance tests require a live database to make changes to, as well as a seed database dump.sql file located in tests/_data
To generate a clean dump.sql file, use WP-CLI to create an export a clean database dump. This will delete all existing data in the database.
wp db drop --yes && wp db create && wp db export tests/_data/dump.sqlTo keep your existing data when running Acceptance tests instead of having it be overwritten by the dump.sql file, it is recommended to create a separate database for testing and update the DB_NAME value in the .env file.
To run the tests in your local WordPress environment, you can use the following commands from the root of the plugin directory:
# Run all tests in a test suite
vendor/bin/codecept run <suite-name> # e.g. vendor/bin/codecept run Integration
# Run a specific test file
vendor/bin/codecept run tests/<suite-name>/<test-file> # e.g. vendor/bin/codecept run tests/Integration/SampleTest.php
# Run a specific test method
vendor/bin/codecept run tests/<suite-name>/<test-file>:<test-method> # e.g. vendor/bin/codecept run tests/Integration/SampleTest.php:testMethod
Important
If you are using LocalWP, make sure to run the tests from inside the LocalWP shell at the root of the plugin directory:
# Switch to the plugin directory
cd wp-content/plugins/snapwp-helper
# Run all tests in a test suite
vendor/bin/codecept run <suite-name> # e.g. vendor/bin/codecept run IntegrationWhen using a dockerized test environment, Codeception tests must be run inside the docker container.
While you can always connect to the container and run the tests manually, you can also use the following commands to run the tests from your host machine (outside the container), by using the bin/run-codeception.sh script with the necessary environment variables.
# Run the Integration suite.
SUITES=Integration bin/run-codeception.sh
# Run the Acceptance suite.
SUITES=Aceptance bin/run-codeception.sh
# Run a specific test method in a specific file.
SUITES="tests/Integration/SampleTest.php:testSampleFunction" bin/run-codeception.shTo generate code coverage reports, you can use the previous commands with the --coverage flag. In some cases you may need to set the XDEBUG_MODE environment variable to coverage to enable code coverage.
# Run code coverage and generate a HTML report.
XDEBUG_MODE=coverage vendor/bin/codecept run <suite-name> --coverage --<report-type> # e.g. XDEBUG_MODE=coverage vendor/bin/codecept run Integration --coverage --coverage-htmlThis project uses @wordpress/e2e-test-utils-playwright to run end-to-end tests using Playwright.
Tests are located in the tests/e2e-playwright directory.
To run the Playwright tests, you can use the following commands:
# Run the test suite
npm run test:e2e
# Run the test suite in UI mode
npm run test:e2e:uiThis project uses Semantic Versioning. When making a release, update the version number according to the following rules:
- Increment the major (
X.y.z) version when making breaking API changes. - Increment the minor (
x.Y.z) version when adding new features or functionality in a backwards-compatible manner. - Increment the patch (
x.y.Z) version when making backwards-compatible bug fixes only.
Note
Versioning is a machine tool for developers. It is not a marketing tool for users - that's what changelogs and release announcements are for. So, don't worry too much about version numbers. Just follow the rules above.
As will all other Code Contributions, the release process is managed through Pull Requests. When you are ready to make a release, create a new branch from develop and make the necessary changes to update the version number (in README, plugin header, constants, etc.) and the changelog.
One the changes are made, and the PR is merged, you should push a copy of the develop branch to the main branch, and then create a new GitHub release with the version number and a summary of the changes.