{"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":"python","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":[{"wrong":"from percy.runner import PercyRunner","symbol":"Client","correct":"from percy import Client"},{"symbol":"Runner","correct":"from percy import Runner"},{"symbol":"Config","correct":"from percy import Config"}],"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,"search_vec":"'2.0.2':43 'activ':46 'break':59 'captur':21 'chang':60 'ci/cd':64 'client':3,10 'comparison':37 'current':40 'cycl':48 'develop':47 'enabl':20 'frequent':50 'improv':53 'includ':51 'integr':12 'librari':6 'major':56 'minor':52 'occasion':55 'page':25 'perci':1,5,17,33 'percy.io':18 'platform':34 'provid':7 'python':2,9 'regress':14,63 'snapshot':22,65 'test':15,27,61,66 'upload':29 'version':42,57 'visual':13,36,62 'web':24","created_at":"2026-04-17T01:22:00.305913+00:00","updated_at":"2026-04-17T01:22:00.305913+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.2","cli_name":"percy","cli_version":"sh: 1: percy: not found","type":"library","homepage":"https://percy.io","github":"https://github.com/percy/python-percy-client","docs":null,"changelog":null,"pypi":"https://pypi.org/project/percy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}