> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# wave/chromatic

Chromatic ensures consistency in UI components, down to the pixel.
Every commit is automatically tested for visual changes in the cloud.
Chromatic - https://www.chromaticqa.com/
Orb source code - https://github.com/waveaccounting/orb-chromatic

Note that this only support yarn for now


## Commands

### test-accept-all-changes

This command will run chromatic and auto-accept all changes to maintain a clean branch.

Typically this should only be run on the main branch.

https://docs.chromaticqa.com/setup_ci#maintain-a-clean-main-branch
https://circleci.com/docs/2.0/configuration-reference/#filters-1


| Parameter | Type | Default | Description |
|---|---|---|---|
| `CHROMATIC_APP_CODE` | string |  |  |
| `CHROMATIC_PROJECT_TOKEN` | string |  |  |
| `chromatic_options` | string |  | Additional parameters to pass to chromatic command |

### test-exit-cleanly-on-changes

Run a chromatic test on the current branch, exiting cleanly unless there are errors.

If you are using the chromatic integration (recommended) then you will want to let
chromatic handle reporting back the status of your snapshots. This command itself
will only fail if the tests failed to run. If they succeeded with changes this command
will succeed and chromatic will report back the number of changes.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `CHROMATIC_APP_CODE` | string |  |  |
| `CHROMATIC_PROJECT_TOKEN` | string |  |  |
| `chromatic_options` | string |  | Additional parameters to pass to chromatic command |

## Jobs

### run-and-accept-all

This job will run chromatic and auto-accept all changes to maintain a clean branch

Pleae ensure you are filtering by branch when using this job

https://circleci.com/docs/2.0/configuration-reference/#filters-1
https://docs.chromaticqa.com/setup_ci#maintain-a-clean-main-branch


| Parameter | Type | Default | Description |
|---|---|---|---|
| `CHROMATIC_APP_CODE` | string |  |  |
| `CHROMATIC_PROJECT_TOKEN` | string |  |  |
| `after_test` | steps |  | Steps to execute after testing is run (i.e. cache save) |
| `before_test` | steps |  | Steps to execute before testing is run (i.e. cache restore) |
| `chromatic_options` | string |  | Additional parameters to pass to chromatic command |
| `node_version` | string | 10 |  |
| `resource_class` | string | medium | Resource class |

### test

Run a chromatic test on the current branch. Only runs against changed stories. Report all changes. Exit non-0 only if any components fail to load


| Parameter | Type | Default | Description |
|---|---|---|---|
| `CHROMATIC_APP_CODE` | string |  |  |
| `CHROMATIC_PROJECT_TOKEN` | string |  |  |
| `after_test` | steps |  | Steps to execute after testing is run (i.e. cache save) |
| `before_test` | steps |  | Steps to execute before testing is run (i.e. cache restore) |
| `chromatic_options` | string |  | Additional parameters to pass to chromatic command |
| `node_version` | string | 10 |  |
| `resource_class` | string | medium | Resource class |

## Executors

### node

Circle CI standard node docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | string | medium | Resource class |
| `version` | string | 10 |  |

## Examples

### config-for-large-teams

Recommended Config

This config is optimized for larger teams, where having chromatic run on every commit
would be prohibitively expensive

The main workflow jobs will run on every commit.
Your approval workflow jobs will run only after a human clicks "approve"

Note that it's mandatory to run an 'accept-all' job on main after each merge. This is to set the correct and up-to-date Chromatic baseline snapshots for feature branches.


```yaml
orbs:
  chromatic: wave/chromatic@x.y.z
version: 2.1
workflows:
  main-workflow:
    jobs:
      - chromatic/run-and-accept-all:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          chromatic_options: '--only-changed --untraced ''package.json'' --untraced ''yarn.lock'''
          filters:
            branches:
              only: main
          resource_class: xlarge
  required-approval:
    jobs:
      - ready:
          filters:
            branches:
              ignore: main
          type: approval
      - chromatic/test:
          chromatic_options: '--only-changed --untraced ''package.json'' --untraced ''yarn.lock'''
          requires:
            - ready
          resource_class: xlarge
  supplemental-expensive-approval:
    jobs:
      - ready:
          filters:
            branches:
              ignore: main
          type: approval
      - chromatic/test:
          requires:
            - ready
          resource_class: xlarge
```

### config-for-small-teams

Recommended Config

This config is optimized for smaller teams, where having Chromatic run the full suite on every commit is unlikely to put you over your quota

Note that it's mandatory to run an 'accept-all' job on main after each merge. This is to set the correct and up-to-date Chromatic baseline snapshots for feature branches.


```yaml
orbs:
  chromatic: wave/chromatic@x.y.z
version: 2.1
workflows:
  main-workflow:
    jobs:
      - chromatic/test:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          filters:
            branches:
              ignore: main
      - chromatic/run-and-accept-all:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          filters:
            branches:
              only: main
```

### keep-main-clean

It is possible that changes you have approved on a feature branch may
still make it into main as unapproved. While chromatic is working hard
to make this process perfectly seamless, they have provided a simple
solution to make sure that your main branch is always clean.

Simply run the `run-and-accept-all` job on your main branch to ensure
that it is always passing on Chromatic.

Note that in order to safely use this you MUST run `chromatic/test` on feature branches


```yaml
orbs:
  chromatic: wave/chromatic@x.y.z
version: 2.1
workflows:
  your-workflow:
    jobs:
      - chromatic/run-and-accept-all:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          filters:
            branches:
              only: main
```

### run-all-when-ready

Only run the full Chromatic suite when a human clicks "approve"

This avoids running tests on every commit and wasting your snapshot quota.


```yaml
orbs:
  chromatic: wave/chromatic@x.y.z
version: 2.1
workflows:
  ui:
    jobs:
      - ready:
          filters:
            branches:
              ignore: main
          type: approval
      - chromatic/test:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          requires:
            - ready
```

### run-on-every-commit

Run chromatic on every commit (only changed files)


```yaml
orbs:
  chromatic: wave/chromatic@x.y.z
version: 2.1
workflows:
  your-workflow:
    jobs:
      - chromatic/test:
          CHROMATIC_APP_CODE: your_unique_code
          CHROMATIC_PROJECT_TOKEN: your_project_token
          chromatic_options: '--only-changed --untraced ''package.json'' --untraced ''yarn.lock'''
```