Looking for good documentation on how to get started on a straight forward CLI workflow.

[alphex]

I work on smaller projects that routinely don't have the budget or scale to warrant a full CI/CD workflow, but become complicated enough, eventually where Visual Regression testing becomes useful.

I'm hoping someone here can share a workflow with Percy that gives me the steps and gives me example documentation/configuration files - to do the following.

I want to percy to be able to establish baseline screen shots against a production URL, and point percy at "www.domain.com", and have it look at a list of paths on that server, to build that initial set of screenshots as a baseline. (where "www" in this example is my production environment)

And then be able to give it an arbitrary domain, like. "branch-name.domain.com" (where "branch-name" is a dev server for our production environment, and can be any subdomain as the branches change...), and have it look at the same list of paths, and build screenshots for those, so that I can then share the results via a "https://percy.io/12345/project-name" URL, and let my client validate that the work is complete and not blowing up the website.

I've tried to follow the documentaton on perci cli, using the percy snapshot snapshots.yml example on the website, but it leaves me with no follow up direction one I figure out how to write the list of urls, and how to run the command.

Does anyone have an use case like this they can share with me?

Thanks!

[Robdel12]

Hey @alphex! You're going to be slightly going against how Percy works to do this -- Percy's baseline picking logic is facilitated by git. To do what you're looking to do, you'll have to take control of the base picking logic slightly. We outline that in this doc: https://docs.percy.io/docs/comparing-two-urls-to-each-other

Using the snapshot CLI command, you'll need to provide a name for each snapshot to override using the URL as the name. That way the snapshots would be able to compare to each other.

[wwilsman]

I wanted to add that if you're using the latest version of the CLI, the percy snapshot command also accepts a --base-url flag that will be used as the base URL for any snapshots with relative URLs.

So if you have this snapshots.yml:

- /about
- /contact
- /blog
- /etc

You can take snapshots of two different base-urls like so:

# to take snapshots of the production branch:
PERCY_BRANCH=production \
percy snapshot snapshots.yml --base-url https://www.foobar.com

# to take snapshots of the staging branch:
PERCY_BRANCH=staging \
PERCY_TARGET_BRANCH=production \
percy snapshot snapshots.yml --base-url https://staging.foobar.com

If the project is under version control and you're running the commands in the correct branches, you won't need to add the PERCY_BRANCH variable. Similarly, if you have your project's baseline set to your production branch, you won't have to set the PERCY_TARGET_BRANCH variable either since they will always compare with the baseline by default.

We're slowly updating our docs to be compatible with the new CLI, and this doc will likely get an update soon as well. 😃

[alphex]

@wwilsman
--base-url is reporting it needs to start with a slash, like a file path. I'm seeing that as well in the documentation.

When i try to pass a FQDN in, I get this.

export PERCY_BRANCH=production
percy snapshot snapshots.yml --base-url=https://alphex.com
[percy] The base-url flag must begin with a slash.

... your reply is EXACTLY what I need, but its not liking a domain name ...

Should I be using -h ? --allowed-hostname ?

I'm gonna go give that shot.

thoughts?

Thank you!!!

[alphex]

Nope, that tried to render something at //localhost:5339.

Thank you.

[wwilsman]

Make sure you're on the latest version of the CLI. It only needs to start with a slash if you are snapshotting a static directory

https://github.com/percy/cli/blob/master/packages/cli-snapshot/src/commands/snapshot.js#L79

[alphex]

@wwilsman
After cleaning NPM up a bunch, I think I got this working... let me poke, and I'll mark this answered if everything is good.

Thank you SO MUCH for your help.

[alphex]

The solution from @wwilsman above answered my questions.

I have a working Visual Regression system that I can test from the command line.

PERCY_TOKEN=xxx \
PERCY_SNAPSHOT=production \
percy snapshot snapshots.yml --base-url https://www.website.com

PERCY_BRANCH=dev \
PERCY_TARGET_BRANCH=staging \
percy snapshot snapshots.yml --base-url https://dev.website.com

And set up your snapshots.yml file with the paths, as ...

- path/to/page
- path/to/another/page
- path/to/yet/another/page

To generate DIFFS for those three pages against your PROD and DEV environments in the percy commands above.

I'm still exploring this, but it does the work I needed it to do!