PHPackages sitegeist/monocle-backstopjs - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. sitegeist/monocle-backstopjs ActiveNeos-plugin[Testing & Quality](/categories/testing) sitegeist/monocle-backstopjs ============================ BackstopJS Connector for Sitegeist.Monocle v1.3.0(3y ago)922.5k↓36.8%2[1 PRs](https://github.com/sitegeist/Sitegeist.Monocle.BackstopJS/pulls)1GPL-3.0-or-laterPHP Since Jan 26Pushed 3y ago3 watchersCompare [ Source](https://github.com/sitegeist/Sitegeist.Monocle.BackstopJS)[ Packagist](https://packagist.org/packages/sitegeist/monocle-backstopjs)[ RSS](/packages/sitegeist-monocle-backstopjs/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (6)Dependencies (4)Versions (10)Used By (1) Sitegeist.Monocle.BackstopJS ============================ [](#sitegeistmonoclebackstopjs) [BackstopJS](https://garris.github.io/BackstopJS) connector for the Sitegeist.Monocle Styleguide This package implements the command `./flow backstop:Configuration` to create a BackstopJS configuration file for a whole Monocle styleguide to test all prototypes with all propSets in all viewports. The generated configuration and scenarios can be adjusted via package setting or via `@styleguide.options.backstop`. ### Authors & Sponsors [](#authors--sponsors) - Martin Ficzel - *The development and the public-releases of this package was generously sponsored by our customer and our employer .* Installation ------------ [](#installation) Sitegeist.Monocle.BackstopJS is available via packagist run `composer require sitegeist/monocle-backstopjs`. We use semantic-versioning so every breaking change will increase the major-version number. Basic Tutorial -------------- [](#basic-tutorial) 1. Install BackstopJS: `npm install -g backstopjs` or install BackstopJS as dev depencency of your project 2. Sitegeist.Monocle.BackstopJS: `composer require sitegeist/monocle-backstopjs` 3. Create BackstopJS Configuration: `./flow backstop:configuration --package-key Vendor.Site --base-uri http://127.0.0.1:8081 > custom-backstop.json` 4. Start Flow Webserver: `FLOW_CONTEXT=Development/VisualRegressionTesting ./flow server:run` 5. Create Reference Files: `backstop reference --config=custom-backstop.json` 6. Run Test: `backstop test --config=custom-backstop.json` CLI Command ----------- [](#cli-command) The package provides a single cli command that can be that create a backstop js configuration on the fly for a given site package and baseUri. ``` USAGE: ./flow backstop:configuration [] OPTIONS: --base-uri the base uri, if empty `http://127.0.0.1:8081` is assumed --package-key the site-package, if empty the default site package is used --report the reports to generate seperated by comma, possible keys are 'browser', 'CI' and 'json' ``` Configuration ------------- [](#configuration) The generated backstop configuration is configured via `Settings.yaml` and the `@styleguide.options.backtop`annotation for fusion prototypes. Settings.yaml: ``` Sitegeist: Monocle: BackstopJS: # if enabled only prototypes that have @styleguide.options.backstop.default = true will # be included, by default all prototypes from the styleguide are included defaultOptIn: false # if enabled only propSets from prototypes that have @styleguide.options.backstop.propSets = true # will be included, by default all propSets from the styleguide are included propSetOptIn: false # if enabled only useCases from prototypes that have @styleguide.options.backstop.useCases = true # will be included, by default all useCases from the styleguide are included useCaseOptIn: false # template for the generated backstop.json file # the keys 'id','viewports','scenarios' and 'pathes' are # replaced by the backstop:configuration command # all other keys can be adjusted as needed # See: https://github.com/garris/BackstopJS/blob/master/README.md configurationTemplate: ... # template for each scenario, the keys 'label' and 'url' are replaced # by the backstop:configuration command, everything else can be adjusted as needed # See: https://github.com/garris/BackstopJS/blob/master/README.md#advanced-scenarios scenarioTemplate: ... ``` All settings can be overwritten for each site-package to adjust to multi site environments ``` Sitegeist: Monocle: packages: 'Vendor.Site': BackstopJS: configurationTemplate: paths: bitmaps_reference: 'DistributionPackages/Vendor.Site/Test/BackstopJS/References' engine_scripts: 'DistributionPackages/Vendor.Site/Test/BackstopJS/EngineScripts' bitmaps_test: 'Data/Temporary/BackstopJS/Vendor.Site/Test' html_report: 'Data/Temporary/BackstopJS/Vendor.Site/HtmlReport' ci_report: 'Data/Temporary/BackstopJS/Vendor.Site/CiReport' ``` Prototype.fusion: ``` prototype(Vendor.Site:Component) < prototype(Neos.Fusion:Component) { @styleguide { options { backstop { # enable or disable proptype the default depends on # the `itemOptIn` setting default = true # enable or disable the propSet inclusion, the default # depends on `propSetOptIn` settings propSets = true # enable or disable the useCases inclusion, the default # depends on `useCaseOptIn` settings useCases = true # configure scenario settings scenario { delay = 2000 hoverSelector = '.button' } } } } } ``` ### Advanced scenarios [](#advanced-scenarios) BackstopJS offers quite a bit of settings to adjust specific scenarios which is documented here . While the general scenario template can be adjusted via Settings.yaml the scenario configuration of each prototyoe can be adjusted by the fusion annotations `@styleguide.options.backstop.scenario`. All keys defined here there will override the generated scenario. Common problems and solutions ----------------------------- [](#common-problems-and-solutions) ### LazyLoading of Images [](#lazyloading-of-images) If the images in the project use lazy loading it is quite likely that the images are not reliably loaded before the screenshot ist taken. This can be mitigated with by disabling the lazy loading in the styleguide. The following fusion code that will disable layzyloading for `Sitegeist.Kaleidoscope` and `Sitegeist.Lazybones`is included via FlowContext `Development/VisualRegressionTesting`. ``` // // Disable lazy loading via loading="lazy" from Sitegeist.Kaleidoscope // prototype(Sitegeist.Kaleidoscope:Image) { loading.@process.override = 'eager' } prototype(Sitegeist.Kaleidoscope:Picture) { loading.@process.override = 'eager' } // // Disable lazy loading via lazysizes.js from Sitegeist.Lazybones // prototype(Sitegeist.Lazybones:Image) { lazy.@process.override = false } prototype(Sitegeist.Lazybones:Picture) { lazy.@process.override = false } ``` !!! Do not include this code in the regular fusion code for Deveopment or Production !!! Alternatively you can also use the following options: 1. Configure a delay in the setting `Sitegeist.Monocle.BackstopJS.scenarioTemplate.delay: 3000` 2. Configure a delay for specific prototypes `@styleguide.options.backstop.scenario.delay = 3000` 3. Configure an `onBeforeScript` in the setting `Sitegeist.Monocle.BackstopJS.configurationTemplate.onBeforeScript`see that ensures that responsive images have been loaded. ### Cross platform rendering inconsistencies [](#cross-platform-rendering-inconsistencies) Since the rendering especially of fonts has slight deviations between different operation systems it is important to run the tests always in a very similar environment to avoid false errors. BackstopJS come with a `--docker` option that will execute all tests using a docker container running headless chrome on linux. *If the `--docker` option is used make sure to call the `./flow backstop:configuration` command with a `--base-uri` that can be reolved from the docker container like in the example below.* ``` ./flow backstop:configuration --base-uri http://host.docker.internal:8081 > backstop.json && backstop test --config=backstop.json --docker ``` - When using ./flow server run use http instead of https - The backstop docker-container will likely not know about local hostname to generate the backstiothe http-port of the development nginx container Contribution ------------ [](#contribution) We will gladly accept contributions. Please send us pull requests. ### Health Score 35 — LowBetter than 80% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity34 Limited adoption so far Community14 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 96.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~127 days Recently: every ~147 days Total 6 Last Release 1299d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/829b4ccb51e8cff3c1e4b59d60cfe8d1b86f6d77fc31a6b3fc99227f432542ca?d=identicon)[mficzel](/maintainers/mficzel) --- Top Contributors [![mficzel](https://avatars.githubusercontent.com/u/1309380?v=4)](https://github.com/mficzel "mficzel (28 commits)")[![bwaidelich](https://avatars.githubusercontent.com/u/307571?v=4)](https://github.com/bwaidelich "bwaidelich (1 commits)") --- Tags cineoscmsvisual-regression-testing ### Embed Badge ![Health badge](/badges/sitegeist-monocle-backstopjs/health.svg) ``` [![Health](https://phpackages.com/badges/sitegeist-monocle-backstopjs/health.svg)](https://phpackages.com/packages/sitegeist-monocle-backstopjs) ``` ### Alternatives [phpspec/prophecy Highly opinionated mocking framework for PHP 5.3+ 8.5k551.7M682](/packages/phpspec-prophecy)[brianium/paratest Parallel testing for PHP 2.5k118.8M754](/packages/brianium-paratest)[beberlei/assert Thin assertion library for input validation in business models. 2.4k96.9M570](/packages/beberlei-assert)[orchestra/testbench Laravel Testing Helper for Packages Development 2.2k39.1M32.1k](/packages/orchestra-testbench)[phpspec/phpspec Specification-oriented BDD framework for PHP 7.1+ 1.9k36.7M3.1k](/packages/phpspec-phpspec)[phpstan/phpstan-symfony Symfony Framework extensions and rules for PHPStan 78768.9M1.5k](/packages/phpstan-phpstan-symfony) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)