percy/percy-selenium-python

Percy visual testing for Python Selenium

percy-selenium-python

Percy visual testing for Python Selenium.

Installation

npm install @percy/cli:

$ npm install --save-dev @percy/cli

pip install Percy selenium package:

$ pip install percy-selenium

Usage

This is an example test using the percy_snapshot function.

from percy import percy_snapshot

browser = webdriver.Firefox()
browser.get('http://example.com')
​
# take a snapshot
percy_snapshot(browser, 'Python example')

Running the test above normally will result in the following log:

[percy] Percy is not running, disabling snapshots

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [python test command]
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Snapshot taken "Python example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Configuration

percy_snapshot(driver, name[, **kwargs])

• driver (required) - A selenium-webdriver driver instance
• name (required) - The snapshot name; must be unique to each snapshot
• **kwargs - See per-snapshot configuration options

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate

Percy on Automate

Usage

This is an example test using the percy_screenshot function. percy_screenshot(driver, name, options) [ needs @percy/cli 1.27.0-beta.0+ ];

from percy import percy_screenshot

driver = webdriver.Remote("https://hub-cloud.browserstack.com/wd/hub", caps) # using automate session
driver.get('http://example.com')
​
# take a snapshot
percy_screenshot(driver, name = 'Screenshot 1')

• driver (required) - A Selenium driver instance
• name (required) - The screenshot name; must be unique to each screenshot
• options (optional) - There are various options supported by percy_screenshot to server further functionality.
  • sync - Boolean value by default it falls back to false, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+]
  • full_page - Boolean value by default it falls back to false, Takes full page screenshot [From CLI v1.27.6+]
  • freeze_animated_image - Boolean value by default it falls back to false, you can pass true and percy will freeze image based animations.
  • freeze_image_by_selectors -List of selectors. Images will be freezed which are passed using selectors. For this to work freeze_animated_image must be set to true.
  • freeze_image_by_xpaths - List of xpaths. Images will be freezed which are passed using xpaths. For this to work freeze_animated_image must be set to true.
  • percy_css - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
  • ignore_region_xpaths - List of xpaths. elements in the DOM can be ignored using xpath
  • ignore_region_selectors - List of selectors. elements in the DOM can be ignored using selectors.
  • ignore_region_selenium_elements - List of selenium web-element. elements can be ignored using selenium_elements.
  • custom_ignore_regions - List of custom objects. elements can be ignored using custom boundaries. Just passing a simple object for it like below.
    • example: {"top": 10, "right": 10, "bottom": 120, "left": 10}
    • In above example it will draw rectangle of ignore region as per given coordinates.
      • top (int): Top coordinate of the ignore region.
      • bottom (int): Bottom coordinate of the ignore region.
      • left (int): Left coordinate of the ignore region.
      • right (int): Right coordinate of the ignore region.
  • consider_region_xpaths - List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.
  • consider_region_selectors - List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.
  • consider_region_selenium_elements - List of selenium web-element. elements can be considered for diffing and will be ignored by Intelli Ignore using selenium_elements.
  • custom_consider_regions - List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries
    • example:{"top": 10, "right": 10, "bottom": 120, "left": 10}
    • In above example it will draw rectangle of consider region will be drawn.
    • Parameters:
      • top (int): Top coordinate of the consider region.
      • bottom (int): Bottom coordinate of the consider region.
      • left (int): Left coordinate of the consider region.
      • right (int): Right coordinate of the consider region.

Creating Percy on automate build

Note: Automate Percy Token starts with auto keyword. The command can be triggered using exec keyword.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- [python test command]
[percy] Percy has started!
[percy] [Python example] : Starting automate screenshot ...
[percy] Screenshot taken "Python example"
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Refer to docs here: Percy on Automate

percy-selenium-python's Issues

percySnapshot fails silently

Right now there's not really a way to know that a call to percySnapshot succeeds in the test run.

I think that a default behaviour of failing when the connection fails would make things easier to debug in general

percySnapshot(browser=...) changed to percySnapshot(driver=...)

just a heads up -- not a big deal but we stubbed our toe

percySnapshot I guess is being kept for backwards compatibility

you might want to also have a signature transformation

def percySnapshot(browser, *a, **kw):
     return percy_snapshot(driver=browser, *a, **kw)

or not... we just went straight to percy_snapshot(driver=...) but might save someone else from hitting this if they are passing browser as a kwarg

functools.cache is only available on python 3.9

meta-data in setup.py says compatible with python 3.6, 3.7, 3.8, 3.9

however, you added a dependency on functools.cache here: 2934f12

this makes import break in anything before python 3.9

recommend either:

1- update meta-data to accurately say compatible only with 3.9+

2- use functools.lru_cache (this is probably better anyway because .cache is unbounded)

also, you might want to consider adding tox to your CI https://tox.readthedocs.io/en/latest/ so build are validated against multiple versions of python

Migration process from the deprecated "percy" python package is not clear

I decided to migrate from the deprecated package (percy=2.0.2):
https://github.com/percy/python-percy-client

I installed percy-selenium~=1.1.0.

First of all, it's not clear if the "percy" command should be installed by this package:

 % percy config:migrate 
zsh: command not found: percy

Second, it will be nice to have some explanations in docs on how to migrate from the older Python SDK.

For example, I would like to know how we can initialize and finalize builds inside our Django tests:

    def test_regression(self):
        root_static_dir = os.path.join(BASE_DIR, 'frontend/static/v2')
        loader = percy.ResourceLoader(
            root_dir=root_static_dir,
            base_url='/static/v2',
            webdriver=self.driver,
        )
        percy_config = percy.Config(default_widths=[1280, 320])

        self.percy_runner = percy.Runner(loader=loader, config=percy_config)
        self.percy_runner.initialize_build()

        for url in self.urls:
            self.driver.get(self.live_server_url + url)
            time.sleep(1)
            percy_snapshot(driver=self.driver, name=name, widths=[1280, 320])

        self.percy_runner.finalize_build()

I don't see something similar to the older APIs: percy.ResourceLoader, .initialize_build() and .finalize_build().

ImportError: cannot import name 'percySnapshot' from 'percy'

Hey,

after following the steps to setup, I get the following error when trying to run the test:
ImportError: cannot import name 'percySnapshot' from 'percy' (/Users/***/PycharmProjects/test3/lib/python3.7/site-packages/percy/init.py)

Tried to run it with command:
npx percy exec -- python mytest.py

Any idea how to solve it?
Thanks for your help.

Broken support for Selenium Chrome Webdriver

In the envInfo function it assumes that a browserVersion key
is available on the webdriver.capabilities dict. When using the Chrome webdriver browserVersion is not available.

While the code does use dict.get to, I assume, avoid a KeyError exception. It does not properly handle the case in which dict.get does not find the requested key and returns the default None. What ends up happening when using Chrome is you get a vague error from the code trying to concatenate None to a string. Would have been better to just use the standard dict get item method (dict[key]) and get the key error.

It would be nice if you could fix this specific issue, but to help find/avoid other issues it would be good if you could test against the chrome webdriver in addition to firefox.

AttributeError: module 'percy' has no attribute 'Runner'

About

Hi. Similar to GH-41, we observed a few problems, maybe also related to the package transition from percy to percy-selenium, and reported about them at earthobservations/wetterdienst#1017 (comment) ff.

Details

We are observing this error ¹, through dash.testing.composite:

         if self._percy_run:
>           self.percy_runner = percy.Runner(
                loader=percy.ResourceLoader(
                    webdriver=self.driver,
                    base_url="/assets",
                    root_dir=percy_assets_root,
                )
            )
E           AttributeError: module 'percy' has no attribute 'Runner'

We have been able to mitigate it by installing percy manually, after the regular package installation process, as a sort of a workaround, like outlined in earthobservations/wetterdienst@37a2424.

Did you ever see that kind of error on your end?

Footnotes

1. https://github.com/earthobservations/wetterdienst/actions/runs/6354438040/job/17260902996?pr=1017#step:8:875 ↩