PHPackages                             streamtechnologies/visualception - 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. streamtechnologies/visualception

ActiveLibrary[Testing & Quality](/categories/testing)

streamtechnologies/visualception
================================

Visual regression tests integrated in Codeception

025PHP

Since Oct 11Pushed 9y ago3 watchersCompare

[ Source](https://github.com/Stream-Technologies/VisualCeption)[ Packagist](https://packagist.org/packages/streamtechnologies/visualception)[ RSS](/packages/streamtechnologies-visualception/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

VisualCeption
=============

[](#visualception)

Visual regression tests integrated in [Codeception](http://codeception.com/).

[![Build Status](https://camo.githubusercontent.com/c356ffbc792276d54196851cdc780212fe5aef8b5c7aca4d537c2af593b35a53/68747470733a2f2f7472617669732d63692e6f72672f4469676974616c50726f64756374732f636f646563657074696f6e2d6d6f64756c652d76697375616c63657074696f6e2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/DigitalProducts/codeception-module-visualception)

This module can be used to compare the current representation of a website element with an expected. It was written on the shoulders of codeception and integrates in a very easy way.

**Example**

[![](https://camo.githubusercontent.com/43dd28cbae6ffdb8d83716b38ea7ba50a25a4064671c71f895a8d02e6ed208e1/687474703a2f2f7777772e74686577656268617465736d652e636f6d2f56697375616c43657074696f6e2f636f6d706172652e706e67)](https://camo.githubusercontent.com/43dd28cbae6ffdb8d83716b38ea7ba50a25a4064671c71f895a8d02e6ed208e1/687474703a2f2f7777772e74686577656268617465736d652e636f6d2f56697375616c43657074696f6e2f636f6d706172652e706e67)

How it works
------------

[](#how-it-works)

VisualCeption uses a combination of the "make a screenshot" feature in webdriver, imagick and jquery to compare visual elements on a website. This comparison is done in five steps:

1. **Take a screenshot** of the full page using webdriver.
2. **Calculate the position** and size of the selected element using jquery.
3. **Crop the element** out of the full screenshot using imagick.
4. **Compare the element** with an older version of the screenshot that has been proofed as valid using imagick. If no previous image exists the current image will be used fur future comparions. As an effect of this approach the test has to be **run twice** before it works.
5. If the deviation is too high **throw an exception** that is caught by Codeception.

Requirements
------------

[](#requirements)

VisualCeption needs the following components to run:

- **Codeception** VisualCeption is a module for [Codeception](http://codeception.com/). It will need a running version of this tool.
- **Imagick** For comparing two images VisualCeption is using the imagick library for php. For more information visit [php.net](http://www.php.net/manual/de/book.imagick.php) or the [installation guide](http://www.php.net/manual/en/imagick.setup.php).
- **WebDriver module** This tool only works with the webdriver module in Codeception at the moment.

Installation
------------

[](#installation)

### Bootstrap

[](#bootstrap)

Add the module to `_bootstrap.php`.

`include_once "/path/to/module/VisualCeption.php";``include_once "/path/to/module/ImageDeviationException.php";`

### Configuration

[](#configuration)

To use the VisualCeption module you have to configure it.

**Example Configuration**

```
modules:
    enabled:
        - WebDriver:
            url: http://localhost.com
            browser: firefox
        - VisualCeption:
            referenceImageDir: /home/codeception/referenceImages/ # Path to the reference folder (optional, standard is
                                                                  # /VisualCeption/)
            maximumDeviation: 5                                   # deviation in percent
            saveCurrentImageIfFailure: true                       # if true, VisualCeption saves the current
```

- **referenceImageDir** VisualCeption uses an "old" image for calculating the deviation. These images have to be stored in the system. This is the corresponding directory.
- **maximumDeviation** When comparing two images the deviation will be calculated. If this deviation is greater than the maximum deviation the test will fail.
- **saveCurrentImageIfFailure** When the test fails, the current image will be saved too, so it's easier to change the reference image with this one. The image will appear beside the compare image with the prefix "current."

Usage
-----

[](#usage)

VisualCeption is really easy to use. There are only two methods that will be added to $I `seeVisualChanges` and `dontSeeVisualChanges`.

```
$I->seeVisualChanges( "uniqueIdentifier1", "elementId1" );
$I->dontSeeVisualChanges( "uniqueIdentifier2", "elementId2" );

$I->dontSeeVisualChanges( "uniqueIdentifier3", "elementId3" [, array("excludeElement1", "excludeElement2")] );
```

- **uniqueIdentifier** For comparing the images it is important to have a stable name. This is the corresponding name.
- **elementId** It is possible to only compare a special div container. The element id can be passed. *You can use all locators that can be used in jQuery*.
- **excludeElements** Optional parameter as string or an array of strings to exclude an element from the screenshot. Maybe there is an animated image in your test container, so you can ignore it. *You can use all locators that can be used in jQuery*.

**Example Usage**

```
$I->seeVisualChanges( "subNavigation", "#subNav" );
$I->dontSeeVisualChanges("content", "div.content", array("#intro"));
```

If you need more information about the test run please use the command line debug option (-d).

Restriction
-----------

[](#restriction)

VisualCeption uses the WebDriver module for making the screenshots. As a consequence we are not able to take screenshots via google chrome as the chromedriver does not allow full page screenshots.

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 63.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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/bb2fa34b4411f6669cc4190cca33f07f44a406e4b2519b93592c41ed0a986697?d=identicon)[StreamTechnologies](/maintainers/StreamTechnologies)

---

Top Contributors

[![DigitalProducts](https://avatars.githubusercontent.com/u/7011638?v=4)](https://github.com/DigitalProducts "DigitalProducts (14 commits)")[![toddy](https://avatars.githubusercontent.com/u/977658?v=4)](https://github.com/toddy "toddy (4 commits)")[![DavertMik](https://avatars.githubusercontent.com/u/220264?v=4)](https://github.com/DavertMik "DavertMik (2 commits)")[![sebastianneubert](https://avatars.githubusercontent.com/u/2872569?v=4)](https://github.com/sebastianneubert "sebastianneubert (1 commits)")[![the-web-hates-me](https://avatars.githubusercontent.com/u/4029191?v=4)](https://github.com/the-web-hates-me "the-web-hates-me (1 commits)")

### Embed Badge

![Health badge](/badges/streamtechnologies-visualception/health.svg)

```
[![Health](https://phpackages.com/badges/streamtechnologies-visualception/health.svg)](https://phpackages.com/packages/streamtechnologies-visualception)
```

###  Alternatives

[phpspec/prophecy

Highly opinionated mocking framework for PHP 5.3+

8.5k551.7M682](/packages/phpspec-prophecy)[vimeo/psalm

A static analysis tool for finding errors in PHP applications

5.8k77.5M6.7k](/packages/vimeo-psalm)[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)[mikey179/vfsstream

Virtual file system to mock the real file system in unit tests.

1.4k108.0M2.7k](/packages/mikey179-vfsstream)[orchestra/testbench

Laravel Testing Helper for Packages Development

2.2k39.1M32.1k](/packages/orchestra-testbench)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)