tr33m4n/codeception-module-percy

Percy https://percy.io module for Codeception

v5.0.9 2024-02-09 19:56 UTC

README

Percy https://percy.io module for Codeception

Requirements

  • Node.js >=14.0.0
  • PHP >= 7.4
  • Composer v2

Installation

composer require --dev tr33m4n/codeception-module-percy

Example Configuration

The following example acceptance.suite.yml configuration assumes the WebDriver module has been configured correctly for your test suite and shows enabling the Percy module and setting some basic configuration:

modules:
    enabled:
        - WebDriver
        - Percy
    config:
      Percy:
        snapshotConfig:
          widths:
            - 1024
            - 768
            - 320
          minHeight: 1080

The following example shows how to configure the percy:process-snapshots in the codeception.yml file:

extensions:
    commands:
        - Codeception\Module\Percy\Command\ProcessSnapshots

Configuration Options

Parameter Type Default Description
snapshotConfig object {} Additional configuration to pass to the "snapshot" functionality
snapshotConfig.percyCSS string null Percy specific CSS to apply to the "snapshot"
snapshotConfig.minHeight int null Minimum height of the resulting "snapshot" in pixels
snapshotConfig.enableJavaScript bool false Enable JavaScript in the Percy rendering environment
snapshotConfig.widths array null An array of integers representing the browser widths at which you want to take snapshots
serializeConfig object {"enableJavaScript": true} Additional configuration to pass to the PercyDOM.serialize method injected into the web driver DOM
collectOnly bool false Setting this to true will only collect snapshots, rather than collect and then send at the end of the run. They can then be sent manually by calling the vendor/bin/codecept percy:process-snapshots command
snapshotServerTimeout int 30 [debug] The length of the time the Percy snapshot server will listen for incoming snapshots and send on to Percy.io (the amount of time needed to send all snapshots after a successful test suite run). No timeout is set by default
snapshotServerPort int 5338 [debug] The port the Percy snapshot server will listen on
snapshotServerDebug bool false [debug] Output verbosely when running the underlying Node Percy library
snapshotFolder string null [debug] Specify a snapshot folder to use when loading or sending snapshots. Folder respects basic glob patterns. Useful if moving snapshots around on the server before sending them with the CLI command
throwOnError bool false [debug] Throw exception on adapter error
instanceId string null [debug] An ID is used to differentiate between one Codeception runs output files to another, ensuring only the current runs output files are cleared on failure. Use this config to pass a custom instance ID

Running

The Percy integration runs automatically with the test suite but will need your PERCY_TOKEN to be set to successfully send snapshots. For more information, see https://docs.percy.io/docs/environment-variables#section-required

Overriding the node path

By default, the node executable used will be the one defined within the PATH of the user running the test suite. This can be overridden however, by setting the environment variable PERCY_NODE_PATH to your preferred location.

Collect only

In some advanced CI setups, it might make sense to collect all snapshots for multiple runs with different parameters and then send them a single time when all runs are complete. This can be achieved by setting the collectOnly config to true. Once all runs are complete, running the command vendor/bin/codecept percy:process-snapshots will then iterate all collected snapshots, send to Percy and then clean up the snapshot folder. The percy:process-snapshots command needs to be configured in the codeception.yml file, see the "Example Configuration" section

Example Test

<?php

class FirstCest
{
    public function frontpageWorks(AcceptanceTester $I)
    {
        $I->amOnPage('/');
        $I->takeAPercySnapshot('My snapshot name');
    }
}

$I->takeAPercySnapshot can optionally be passed an array of additional arguments to override the global settings for percyCSS, minHeight, enableJavaScript and widths on the fly, for example:

use Codeception\Module\Percy\Snapshot;

$I->takeAPercySnapshot('My snapshot name', [
    Snapshot::WIDTHS => [1024, 768, 320], // Browser breakpoint widths
    Snapshot::MIN_HEIGHT => 1080, // Minimum height of the resulting snapshot
    Snapshot::PERCY_CSS => 'iframe { display: none; }', // Percy specific CSS
    Snapshot::ENABLE_JAVASCRIPT => true // Enable/disable JavaScript
]);