README

codeception-module-percy

Percy https://percy.io module for Codeception

Requirements

• Node.js >=14.0.0
• PHP >= 8.1
• 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

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
]);

Development

This module comes with ddev configuration to aid with local development. To setup the project do:

1. Install ddev https://docs.ddev.com/en/stable/users/install/ddev-installation/
2. Run ddev build
3. Optionally run ddev test to run static analysis and Codeception test suites. Note, you'll need a Percy token set for the Codeception test suites to complete

This will composer install deps into a ddev environment. For more information about developing with ddev, see their official documentation