wearenolte / wp-ci-template
Installs: 103
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 10
Forks: 3
Open Issues: 6
Language:Shell
Type:project
Requires
- php: >=8.0
- composer/installers: >=1.0
- nolte-wpackagist/advanced-custom-fields-pro: 6.0.7
- nolte-wpackagist/gravityforms: *
- pantheon-systems/quicksilver-pushback: >=2
- pantheon-systems/wordpress-composer: *
- roots/wp-password-bcrypt: >=1.1.0
- rvtraveller/qs-composer-installer: >=1.1
- vlucas/phpdotenv: >=5.5
- wpackagist-plugin/acf-image-aspect-ratio-crop: *
- wpackagist-plugin/lh-hsts: >=1.25
- wpackagist-plugin/pantheon-advanced-page-cache: >=1.2.0
- wpackagist-plugin/postmark-approved-wordpress-plugin: >=1.17
- wpackagist-plugin/regenerate-thumbnails: >=3.1
- wpackagist-plugin/shortpixel-image-optimiser: >=5.1
- wpackagist-plugin/stream: >=3.9
- wpackagist-plugin/wordpress-seo: >=20.0
- wpackagist-plugin/wp-help: >=1.7.1
- wpackagist-theme/twentytwentythree: >=1.0
Requires (Dev)
- brain/monkey: >=2.2.0
- dealerdirect/phpcodesniffer-composer-installer: >=0.7.0
- phpunit/phpunit: >=9.5.28
- roave/security-advisories: dev-master
- squizlabs/php_codesniffer: >=3.4.0
- wp-coding-standards/wpcs: >=2.2
- dev-master
- dev-dependabot/npm_and_yarn/word-wrap-1.2.4
- dev-dependabot/npm_and_yarn/semver-5.7.2
- dev-lando-updates
- dev-mannuel-patch-1
- dev-composer-update
- dev-composer-updates
- dev-remove-behat
- dev-add-happo.io
- dev-happo/cypress-integration
- dev-shortpixel
- dev-update-plugins
- dev-redis-cache
- dev-disable-cypress-chromeWebSecurity
- dev-unit-testing-integration
- dev-gitignore-fix
- dev-integrate-local-cypress
- dev-update-gitignore
- dev-lando-file
- dev-lean-theme-improvements
This package is auto-updated.
Last update: 2024-11-19 05:03:30 UTC
README
This repository is a reference implementation and start state for a modern WordPress workflow utilizing Composer, Continuous Integration (CI), Automated Testing, and Pantheon.
This repository is meant to be copied one-time by the the Terminus Build Tools Plugin but can also be used as a template.
The Terminus Build Tools plugin will scaffold a new project, including:
- A Git repository
- A Pantheon sandbox site
- Continuous Integration configuration/credential set up
For more details and instructions on creating a new project, see the Terminus Build Tools Plugin.
Important files and directories
/web
Pantheon will serve the site from the /web
subdirectory due to the configuration in pantheon.yml
. This is necessary for a Composer based workflow. Having your website in this subdirectory also allows for tests, scripts, and other files related to your project to be stored in your repo without polluting your web document root or being web accessible from Pantheon. They may still be accessible from your version control project if it is public. See the pantheon.yml
documentation for details.
/web/wp
Even within the /web
directory you may notice that other directories and files are in different places compared to a default WordPress installation. WordPress allows installing WordPress core in its own directory, which is necessary when installing WordPress with Composer.
See /web/wp-config.php
for key settings, such as WP_SITEURL
, which must be updated so that WordPress core functions properly in the relocated /web/wp
directory. The overall layout of directories in the repo is inspired by, but doesn't exactly mirror, Bedrock.
composer.json
This project uses Composer to manage third-party PHP dependencies.
The require
section of composer.json
should be used for any dependencies your web project needs, even those that might only be used on non-Live environments. All dependencies in require
will be pushed to Pantheon.
The require-dev
section should be used for dependencies that are not a part of the web application but are necesarry to build or test the project. Some example are php_codesniffer
and phpunit
. Dev dependencies will not be deployed to Pantheon.
If you are just browsing this repository on GitHub or Bitbucket, you may not see some of the directories mentioned above, such as web/wp
. That is because WordPress core and its plugins are installed via Composer and ignored in the .gitignore
file.
A custom, Composer version of WordPress for Pantheon is used as the source for WordPress core.
Third party WordPress dependencies, such as plugins and themes, are added to the project via composer.json
. The composer.lock
file keeps track of the exact version of dependency. Composer installer-paths
are used to ensure the WordPress dependencies are downloaded into the appropriate directory.
We do not allow plugin installs from the public wpackagist repository. All plugins must be installed from our nolte-wpackagist instead. This ensures only approved plugins are used.
Non-WordPress dependencies are downloaded to the /vendor
directory.
.ci
This .ci
directory is where all of the scripts that run on Continuous Integration are stored. Provider specific configuration files, such as .circle/config.yml
and .gitlab-ci.yml
, make use of these scripts.
The scripts are organized into subdirectories of .ci
according to their function: build
, deploy
, or test
.
Build Scripts .ci/build
Steps for building an artifact suitable for deployment. Feel free to add other build scripts here, such as installing Node dependencies, depending on your needs.
.ci/build/php
installs PHP dependencies with Composer
Build Scripts .ci/deploy
Scripts for facilitating code deployment to Pantheon.
.ci/deploy/pantheon/create-multidev
creates a new Pantheon multidev environment for branches other than the default Git branch- Note that not all users have multidev access. Please consult the multidev FAQ doc for details.
.ci/deploy/pantheon/dev-multidev
deploys the built artifact to either the Pantheondev
or a multidev environment, depending on the Git branch
Automated Test Scripts .ci/tests
Scripts that run automated tests. Feel free to add or remove scripts here depending on your testing needs.
Static Testing .ci/test/static
and tests/unit
Static tests analyze code without executing it. It is good at detecting syntax error but not functionality.
.ci/test/static/run
Runs PHP CodeSniffer with WordPress coding standards, PHP Unit, and PHP syntax checking.tests/unit/bootstrap.php
Bootstraps the Composer autoloadertests/unit/TestAssert.php
An example Unit test. Project specific test files will need to be created intests/unit
.
Visual Regression Testing .ci/test/visual-regression
Visual regression testing uses a headless browser to take screenshots of web pages and compare them for visual differences.
.ci/test/visual-regression/run
Runs BackstopJS visual regression testing..ci/test/visual-regression/backstopConfig.js
The BackstopJS configuration file. Setting here will need to be updated for your project. For example, thepathsToTest
variable determines the URLs to test.
Working locally with Lando
To get started using Lando to develop locally complete these one-time steps. Please note than Lando is an independent product and is not supported by Pantheon. For further assistance please refer to the Lando documentation.
- Install Lando, if not already installed.
- Create a folder to host your project locally.
- Run
lando init
from your project folder and follow the prompts, choosing the Pantheon recipe followed by entering a valid machine token and selecting the Pantheon site created by [the Terminus build tools plugin].(https://github.com/pantheon-systems/terminus-build-tools-plugin). - Run
lando start
to start Lando.- Save the local site URL. It should be similar to
https://<PROJECT_NAME>.lndo.site
.
- Save the local site URL. It should be similar to
- Run
lando composer install --no-ansi --no-interaction --optimize-autoloader --no-progress
to download dependencies - Run
lando pull --code=none
to download the media files and database from Pantheon. - Visit the local site URL saved from above.
You should now be able to edit your site locally. You can stop Lando with lando stop
and start it again with lando start
.
Warning: do NOT push/pull code between Lando and Pantheon directly. All code should be pushed to Bitbucket, which will deploy to Pantheon through its continuous integration service, Pipelines.
Composer, Terminus and wp-cli commands should be run in Lando rather than on the host machine. This is done by prefixing the desired command with lando
. For example, after a change to composer.json
run lando composer update
rather than composer update
.
Testing Locally with Cypress
Cypress is a JavaScript-based end-to-end testing framework. It is built on top of Mocha and Chai, frameworks that run on the browser, and supports Chai’s BDD and TDD assertion styles. Documentation for Cypress can be found here, with API docs here. These include guides on best practices, commands, assertions, and events.
You can find many examples of tests, including tests with stubs, forms, and network requests, in Cypress's Github.
Writing Tests
New tests can be added to tests/cypress/integration/
. Fixture data files can be added to tests/cypress/fixtures/
. The support file tests/cypress/support/index.js
runs before every spec file and is the place to store reusable behavior (such as navigating to the home page).
To create a new spec file, use the syntax test-name_test.spec.js
. Use the Mocha function describe()
to group the tests in each file. Use it()
to identify individual tests. Avoid the temptation to write an it()
function for every assertion, as you might when unit testing. Integration tests can include multiple assertions and will run more efficiently this way.
To reference a component, instead of relying on class names or other brittle selectors, check if it already has a custom data attribute assigned to it, or assign one using the following pattern:
data-{type-of-component}="{component-slug}"
Example: data-molecule="cards/media"
For creating the component slug, use the folder path. In this example, the component php file is in molecules/cards/media.php
Note that for testing across screen sizes, Cypress offers viewport presets for common devices.
Running Tests
To run tests headlessly, run the command composer functional-test
. To run tests within the browser and view step-by-step snapshots, run composer functional-test-open
. To run both Cypress and PHPunit tests, run composer test
.
An mp4 of the most recent run of each spec file is stored in tests/cypress/videos
.