Surface is WordPress starter theme based on Automattic's _s upgraded with many features for development. It supports Sass, ES6, HMR (aka instant live reload) along with full suit of testing frameworks PHP and JS.
Theme itself is still organized in "the WordPress way" and suitable for WordPress.org theme development.
Webpack config is based on Mythic starter theme.
- Webpack as a build tool using Laravel Mix wrapper
- BrowserSync to develop with instant live reload
- Codeception PHP testing suit with wp-browser
- Karma JS unit test runner
- Mocha JS unit test framework
- Chai JS unit assertion library
- Sinon JS unit mocking library
- BackstopJS visual regression tester
- ESlint JS linting tool using WP standard
- Stylelint CSS linting tool using WP standard
In form of a separate branch I included a refactor of CSS with BEM syntax support and partial ITCSS styles organization.
Download Surface from Github and rename the main folder to your brand new theme name i.e. my-new-theme.
To setup theme you will need to rename default strings across theme files to match your new theme name either using included script or manually.
You can setup theme automatically by installing NPM dependencies and running this command in theme's directory:
yarn install
node setup.js
Instead of using automatic setup you can search and replace necessary strings to names for your unique theme. Text editors like Sublime Text or any modern IDE can do that on all files in directory at once.
| Search for: | Replace with: | |
|---|---|---|
'_s' |
'my-new-theme' |
with single quotes |
_s_ |
my_new_theme_ |
|
Text Domain: _s |
Text Domain: my-new-theme |
|
package _s |
package My_New_Theme |
|
_s |
My New Theme |
with space in front |
_s- |
my-new-theme- |
|
--s-- |
my-new-theme |
|
__url__ |
http://mysite.com |
or just http://localhost |
To start developing install NPM dependencies and start watching files for changes:
yarn install
yarn run watch
When theme is ready to be exported for production run yarn run build - this will lint all files for style errors, build and minify them, generate POT translation file and copy only the required files to a new directory inside the theme.
All major test cases are covered:
- JS unit tests - Chai, Sinon and Mocha testing stack running on Karma with Chrome and Firefox headless setup by default,
- PHP unit tests - Codeception unit suit powered by PHPUnit,
- Integration tests - Codeception wpunit suit that implements WP Core automated suite of helpful fixtures and factories,
- Functional tests - Codeception functional suit that emulates and process requests without need to run a web server,
- Acceptance tests - Codeception acceptance suit tests using PhpBrowser (WebDriver solution can easily be configured to support JavaScript),
- Visual regression tests - BackstopJS framework for automatic comparision of DOM elements screenshots.
You can learn how to use Codeception for WordPress in the official guide.
To setup Codeception use Composer:
composer install
Codeception's main config file is located in tests/php/.env.testing. Testing suits require database access, DO NOT provide your current WordPress database name in this config as it is erased and rebuild between tests. It is proffered to have two separate databases setup in TEST_SITE_DB_NAME and TEST_DB_NAME respectively.
Functional and acceptance tests will use a database dump file as a WordPress site data to be testet against. Place it in tmp/_data/dump.sql.
Check wp-browser documentation for more in-depth info on setup and configuration.
Karma setup works without any configuration, only requirements are Firefox version 56 or above and Chrome version 59 or above installed.
To run tests:
yarn run test
BackstopJS takes screenshots of specified DOM elements in selected viewports configured in assets/build/backstop.json and compares them between approved reference and new test case.
The workflow consists of running tests and approving the results as the future reference. To run test:
yarn run visual:test
When test fail, we can approve its results as the new reference:
yarn run visual:approve