Your first Percy build

Your first percy build


This page talks about


The “Hello Percy” program is a simple program that illustrates Percy’s visual testing feature. Use it to run your first Percy build. No framework required.


Note: We use the snapshot command to create our first build. CLI

Get started

Follow the below procedure to create a Percy project, generate build & view comparison results.

1) Install Percy CLI.

Install the @percy/cli dependency.

$ npm install @percy/cli

2) Create a Percy Project.

Let’s create a new Percy project in order to generate builds. After we generate the first build, we will introduce a few visual changes in the application & generate the second build. Post-build generation, we will compare both builds to view the visual comparison results.

a) Visit

b) Go to dashboard & click "Create new project".

c) Specify the "Project name".

d) Click "Create Project".

After the project is created, a token is generated which will identify your project builds to Percy servers. See the following clip to identify the generated token.

3) Set environment variables

Export the token environment variables.


$ export PERCY_TOKEN="<your token here>"
$ export PERCY_BRANCH="<your git branch>"


$ set PERCY_TOKEN="<your token here>"
$ set PERCY_BRANCH="<your git branch>"

# PowerShell
$ $Env:PERCY_TOKEN="<your token here>"
$ $Env:PERCY_BRANCH="<your git branch>"

Note: This is often only configured in your CI environment, but to keep things simple we'll configure it in your shell so that Percy is enabled in your local environment.

4) Generate first build

Let’s create a really simple HTML code and take a snapshot of the same to get things going.

a) Create a index.html file in your project folder with the following contents:

<!DOCTYPE html>
    <title>Todo List</title>
    	body {
    		font-family: system-ui;
    		max-width: 500px;
    		padding: 20px;
    		margin: 20px auto;
    		box-shadow: 0 10px 10px #eee;
      input[type="text"] {
      	width: 100%;
        padding: 12px 20px;
        margin: 8px 0;
        box-sizing: border-box;
        border-radius: 4px;
        border: 1px solid #ccc;
        font-size: 20px;
      ul {
        list-style-type: none;
        margin: 0;
        padding: 0;
      li {
        margin: 8px 0;
        padding: 12px 20px;
        background-color: #995dbb;
        color: white;
        border-radius: 4px;
      li.done {
		    opacity: 0.4;
		    text-decoration: line-through      
      h1 {
      	color: rgba(0,0,0,0.78);
				font-weight: normal;
				margin: 10px auto;
				text-align: center;
    <h1>hello percy!</h1>
    <input type="text" id="new-task" name="new-task" placeholder="What do you want to do?">
    <ul id="task-list">
      <li>Wake Up</li>

b) Create a snapshots.yml file, which identifies the snapshots to be taken to Percy in the generated build.

serve: . 
  - name: Home Page
    url: /index.html

c) Run the build with the following command.

$ npx percy snapshot snapshots.yml

5) Generate second build

To demonstrate Percy’s visual testing quality, let’s introduce visual changes & generate the second build.

a) Make the following changes to line no. 51 of index.html

<li class="done">Exercise</li>

b) Run the build.

$ npx percy snapshot snapshots.yml

6) Results

To view the visual comparison results, click on the finalised build link as shown below:

[percy] Percy has started!
[percy] Snapshot taken: HelloPercy
[percy] Finalized build #2:

You will see the comparison between first and second build highlighting the visual changes as follows:

Finished! 😀

Congratulations, you just completed your first visual testing with Percy comparison! You can make your own changes to the app and re-run the build to check visual changes reflected in Percy.


  • If you're using some application framework, check out our SDKs for it.
  • If your app has a responsive DOM, or a different DOM for Web & Mobile, configure Percy’s SDKs to support the same. Read more