{"id":10027,"library":"percy","title":"Percy Python Client","description":"The `percy` library provides a Python client for integrating visual regression testing with Percy (https://percy.io). It enables capturing snapshots of web pages during tests and uploading them to the Percy platform for visual comparison. It is currently at version 2.0.2, with an active development cycle that frequently includes minor improvements and occasional major versions for breaking changes.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/percy/python-percy-client","tags":["testing","visual regression","CI/CD","snapshot testing"],"install":[{"cmd":"pip install percy","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"PercyRunner","correct":"from percy.runner import PercyRunner"},{"symbol":"percy_snapshot","correct":"from percy.snapshot import percy_snapshot"}],"quickstart":{"code":"import os\nfrom percy.runner import PercyRunner\nfrom percy.snapshot import percy_snapshot\n\n# Percy requires a WebDriver instance (e.g., from Selenium or Playwright).\n# For this example, we'll use a mock driver.\nclass MockWebDriver:\n def __init__(self):\n self.title = \"Mock Page Title\"\n self.current_url = \"http://localhost:8000/mock-page\"\n\n def execute_script(self, script):\n # Simulate returning page HTML or other script results\n if \"document.documentElement.outerHTML\" in script:\n return \"

Hello from Percy!

\"\n return None\n\n# Ensure PERCY_TOKEN is set in your environment variables for actual uploads.\n# Example: export PERCY_TOKEN=\"YOUR_PERCY_TOKEN\"\npercy_token = os.environ.get('PERCY_TOKEN', 'YOUR_PERCY_TOKEN_IF_MISSING')\nif percy_token == 'YOUR_PERCY_TOKEN_IF_MISSING':\n print(\"Warning: PERCY_TOKEN environment variable is not set. Snapshots will not be uploaded.\")\n\nrunner = PercyRunner()\ntry:\n # Start a Percy build\n runner.start_build()\n print(\"Percy build started.\")\n\n # Instantiate the mock driver\n driver = MockWebDriver()\n\n # Take a snapshot\n percy_snapshot(driver, name=\"Example Snapshot 1\", widths=[768, 1280])\n print(\"Snapshot 'Example Snapshot 1' taken.\")\n\n # You can take multiple snapshots in a single build\n # percy_snapshot(driver, name=\"Example Snapshot 2\", fullscreen=True)\n\nfinally:\n # Finalize the Percy build\n runner.finalize_build()\n print(\"Percy build finalized.\")\n","lang":"python","description":"This quickstart demonstrates the basic lifecycle for using the Percy Python client: initialize `PercyRunner`, start a build, take one or more snapshots using a WebDriver instance, and then finalize the build. It requires a `PERCY_TOKEN` environment variable to successfully upload snapshots to Percy. A mock WebDriver is used to make the example runnable without a full browser setup."},"warnings":[{"fix":"Remove `PERCY_PROJECT` from your CI environment variables. Percy now determines the project based on the `PERCY_TOKEN`.","message":"The `PERCY_PROJECT` environment variable is no longer supported or handled by the client library. It was removed in v2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Avoid direct calls to `create_build`. The recommended approach is to simply call `runner.start_build()` which handles the build creation internally. Ensure necessary environment variables (e.g., `PERCY_TOKEN`) are correctly set.","message":"The direct interface for `create_build` on `PercyRunner` was changed significantly in v2.0.0. It is now primarily called internally and accepts only optional arguments, with most build metadata inferred from environment variables.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Set the `PERCY_TOKEN` environment variable in your CI/CD environment or locally (e.g., `export PERCY_TOKEN=\"YOUR_TOKEN\"`). Obtain your token from the Percy project settings on percy.io.","message":"All Percy API interactions, including uploading snapshots, require the `PERCY_TOKEN` environment variable to be set. Without it, the client will run but no snapshots will be uploaded.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Set the `PERCY_TOKEN` environment variable. You can find your project's token in the Percy dashboard.","cause":"The Percy client cannot authenticate with the Percy API without a valid token.","error":"percy: environment variable PERCY_TOKEN missing"},{"fix":"Instead of `runner.create_build()`, simply use `runner.start_build()`. The build creation is now handled automatically within the `start_build` method based on environment variables.","cause":"Attempting to call `create_build` method on `PercyRunner` directly after the v2.0.0 breaking change, which significantly altered its interface and made it mostly internal.","error":"AttributeError: 'PercyRunner' object has no attribute 'create_build'"},{"fix":"Ensure `runner.start_build()` is called before any `percy_snapshot()` calls and that `runner.finalize_build()` is called only after all snapshots are taken, typically in a `finally` block or test teardown.","cause":"You tried to call `percy_snapshot` before `runner.start_build()` was successfully executed, or after `runner.finalize_build()` was called.","error":"Error: The percy:percy-snapshot command cannot be run because a Percy build is not in progress."}]}