A shareable package of CircleCI configuration to integrate with chromatic, written by wave
CommunityUse CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1Add the orbs stanza below your version, invoking the orb:
1
2
orbs:
chromatic: wave/chromatic@3.1.0Use chromatic elements in your existing workflows and jobs.
Opt-in to use of uncertified orbs on your organization’s Security settings page.
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
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
1
2
3
4
5
6
7
8
9
10
11
12
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
Only run the full Chromatic suite when a human clicks "approve" This avoids running tests on every commit and wasting your snapshot quota.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 chromatic on every commit (only changed files)
1
2
3
4
5
6
7
8
9
10
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'''
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
|---|---|---|---|---|
CHROMATIC_APP_CODE - | - | No | '' type: string | string |
CHROMATIC_PROJECT_TOKEN - | - | No | '' type: string | string |
after_test Steps to execute after testing is run (i.e. cache save) | Steps to execute after testing is run (i.e. cache save) | No | [] type: steps | steps |
before_test Steps to execute before testing is run (i.e. cache restore) | Steps to execute before testing is run (i.e. cache restore) | No | [] type: steps | steps |
chromatic_options Additional parameters to pass to chromatic command | Additional parameters to pass to chromatic command | No | '' type: string | string |
node_version - | - | No | '10' type: string | string |
resource_class Resource class | Resource class | No | medium type: string | string |
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
|---|---|---|---|---|
CHROMATIC_APP_CODE - | - | No | '' type: string | string |
CHROMATIC_PROJECT_TOKEN - | - | No | '' type: string | string |
after_test Steps to execute after testing is run (i.e. cache save) | Steps to execute after testing is run (i.e. cache save) | No | [] type: steps | steps |
before_test Steps to execute before testing is run (i.e. cache restore) | Steps to execute before testing is run (i.e. cache restore) | No | [] type: steps | steps |
chromatic_options Additional parameters to pass to chromatic command | Additional parameters to pass to chromatic command | No | '' type: string | string |
node_version - | - | No | '10' type: string | string |
resource_class Resource class | Resource class | No | medium type: string | string |
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
|---|---|---|---|---|
CHROMATIC_APP_CODE - | - | No | '' type: string | string |
CHROMATIC_PROJECT_TOKEN - | - | No | '' type: string | string |
chromatic_options Additional parameters to pass to chromatic command | Additional parameters to pass to chromatic command | No | '' type: string | string |
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
|---|---|---|---|---|
CHROMATIC_APP_CODE - | - | No | '' type: string | string |
CHROMATIC_PROJECT_TOKEN - | - | No | '' type: string | string |
chromatic_options Additional parameters to pass to chromatic command | Additional parameters to pass to chromatic command | No | '' type: string | string |
Circle CI standard node docker image
| PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
|---|---|---|---|---|
resource_class Resource class | Resource class | No | medium type: string | string |
version - | - | No | '10' type: string | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
commands:
test-accept-all-changes:
description: |
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
parameters:
CHROMATIC_APP_CODE:
default: ""
type: string
CHROMATIC_PROJECT_TOKEN:
default: ""
type: string
chromatic_options:
default: ""
description: Additional parameters to pass to chromatic command
type: string
steps:
- run:
command: |
export CHROMATIC_APP_CODE="${CHROMATIC_APP_CODE:=<<parameters.CHROMATIC_APP_CODE>>}"
export CHROMATIC_PROJECT_TOKEN="${CHROMATIC_PROJECT_TOKEN:=<<parameters.CHROMATIC_PROJECT_TOKEN>>}"
yarn chromatic test --auto-accept-changes <<parameters.chromatic_options>>
name: Chromatic - accept all changes
test-exit-cleanly-on-changes:
description: |
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.
parameters:
CHROMATIC_APP_CODE:
default: ""
type: string
CHROMATIC_PROJECT_TOKEN:
default: ""
type: string
chromatic_options:
default: ""
description: Additional parameters to pass to chromatic command
type: string
steps:
- run:
command: |
export CHROMATIC_APP_CODE="${CHROMATIC_APP_CODE:=<<parameters.CHROMATIC_APP_CODE>>}"
export CHROMATIC_PROJECT_TOKEN="${CHROMATIC_PROJECT_TOKEN:=<<parameters.CHROMATIC_PROJECT_TOKEN>>}"
yarn chromatic test --exit-zero-on-changes --exit-once-uploaded <<parameters.chromatic_options>>
name: Chromatic - test stories
description: |
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
examples:
config-for-large-teams:
description: |
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.
usage:
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:
description: |
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.
usage:
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:
description: |
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
usage:
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:
description: |
Only run the full Chromatic suite when a human clicks "approve"
This avoids running tests on every commit and wasting your snapshot quota.
usage:
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:
description: |
Run chromatic on every commit (only changed files)
usage:
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'
executors:
node:
description: Circle CI standard node docker image
docker:
- image: cimg/node:<<parameters.version>>
parameters:
resource_class:
default: medium
description: Resource class
type: string
version:
default: "10"
type: string
resource_class: <<parameters.resource_class>>
jobs:
run-and-accept-all:
description: |
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
executor:
name: node
resource_class: <<parameters.resource_class>>
version: <<parameters.node_version>>
parameters:
CHROMATIC_APP_CODE:
default: ""
type: string
CHROMATIC_PROJECT_TOKEN:
default: ""
type: string
after_test:
default: []
description: Steps to execute after testing is run (i.e. cache save)
type: steps
before_test:
default: []
description: Steps to execute before testing is run (i.e. cache restore)
type: steps
chromatic_options:
default: ""
description: Additional parameters to pass to chromatic command
type: string
node_version:
default: "10"
type: string
resource_class:
default: medium
description: Resource class
type: string
steps:
- checkout
- run:
command: date +%F > ci_date
name: Save date
- steps: <<parameters.before_test>>
- run:
command: yarn install --immutable
name: Yarn Install
- test-accept-all-changes:
CHROMATIC_APP_CODE: <<parameters.CHROMATIC_APP_CODE>>
CHROMATIC_PROJECT_TOKEN: <<parameters.CHROMATIC_PROJECT_TOKEN>>
chromatic_options: <<parameters.chromatic_options>>
- steps: << parameters.after_test >>
test:
description: |
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
executor:
name: node
resource_class: <<parameters.resource_class>>
version: <<parameters.node_version>>
parameters:
CHROMATIC_APP_CODE:
default: ""
type: string
CHROMATIC_PROJECT_TOKEN:
default: ""
type: string
after_test:
default: []
description: Steps to execute after testing is run (i.e. cache save)
type: steps
before_test:
default: []
description: Steps to execute before testing is run (i.e. cache restore)
type: steps
chromatic_options:
default: ""
description: Additional parameters to pass to chromatic command
type: string
node_version:
default: "10"
type: string
resource_class:
default: medium
description: Resource class
type: string
steps:
- checkout
- run:
command: date +%F > ci_date
name: Save date
- steps: <<parameters.before_test>>
- run:
command: yarn install --immutable
name: Yarn Install
- test-exit-cleanly-on-changes:
CHROMATIC_APP_CODE: <<parameters.CHROMATIC_APP_CODE>>
CHROMATIC_PROJECT_TOKEN: <<parameters.CHROMATIC_PROJECT_TOKEN>>
chromatic_options: <<parameters.chromatic_options>>
- steps: << parameters.after_test >>
version: 2.1