0
# Core Operations
1

2
Essential Percy workflow commands for starting, stopping, and executing visual tests with any test runner or static content. These commands form the foundation of Percy's visual testing workflow.
3

4
## Capabilities
5

6
### Percy Exec
7

8
Start Percy, execute a command (typically a test suite), then automatically stop Percy when the command completes. This is the most common Percy workflow.
9

10
```bash { .api }
11
/**
12
 * Execute command with Percy visual testing environment
13
 * Starts Percy server, runs the specified command, then stops Percy
14
 * 
15
 * Usage: percy exec -- <command>
16
 * 
17
 * Options:
18
 *   --parallel          Mark as parallel build (sets PERCY_PARALLEL_TOTAL=-1)
19
 *   --partial           Mark as partial build (sets PERCY_PARTIAL_BUILD=1)
20
 *   --testing           Internal testing flag (hidden)
21
 * 
22
 * Environment variables set:
23
 *   PERCY_SERVER_ADDRESS    Local Percy server URL
24
 *   PERCY_BUILD_ID          Current build identifier
25
 *   PERCY_BUILD_URL         Percy dashboard URL for build
26
 *   PERCY_LOGLEVEL          Current logging level
27
 */
28
percy exec -- <command>
29
```
30

31
**Usage Examples:**
32

33
```bash
34
# Run tests with Percy
35
percy exec -- npm test
36
percy exec -- yarn test
37
percy exec -- pytest
38

39
# Run specific test files
40
percy exec -- npm test -- --grep "visual tests"
41
percy exec -- jest tests/visual/
42

43
# Run with parallel builds
44
percy exec --parallel -- npm test
45

46
# Run partial build (for CI matrix builds)
47
percy exec --partial -- npm run test:unit
48
```
49

50
### Percy Start
51

52
Start the Percy process in the background as a daemon. Use this for long-running processes or when you need fine-grained control over when Percy starts and stops.
53

54
```bash { .api }
55
/**
56
 * Start Percy process in background
57
 * Initializes Percy server and creates a new build
58
 * Must be paired with 'percy stop' to finalize the build
59
 * 
60
 * Usage: percy start
61
 * 
62
 * Returns: Process continues running until 'percy stop' is called
63
 */
64
percy start
65
```
66

67
**Usage Examples:**
68

69
```bash
70
# Start Percy in background
71
percy start
72

73
# Run your tests (Percy server is available at $PERCY_SERVER_ADDRESS)
74
npm test
75

76
# Stop Percy when done
77
percy stop
78
```
79

80
### Percy Stop
81

82
Stop the Percy process and finalize the current build. This uploads any remaining snapshots and marks the build as complete.
83

84
```bash { .api }
85
/**
86
 * Stop Percy process and finalize build
87
 * Uploads pending snapshots and marks build as complete
88
 * Should be called after 'percy start' and test execution
89
 * 
90
 * Usage: percy stop
91
 * 
92
 * Returns: Process exits after build finalization
93
 */
94
percy stop
95
```
96

97
**Usage Examples:**
98

99
```bash
100
# Stop Percy and finalize build
101
percy stop
102

103
# Can be used in scripts
104
percy start
105
npm test
106
percy stop
107
```
108

109
### Percy Ping
110

111
Check if Percy process is currently running and responsive. Useful for debugging and health checks.
112

113
```bash { .api }
114
/**
115
 * Check if Percy process is running
116
 * Tests connectivity to local Percy server
117
 * 
118
 * Usage: percy ping
119
 * 
120
 * Exit codes:
121
 *   0 - Percy is running and responsive
122
 *   1 - Percy is not running or not responsive
123
 */
124
percy ping
125
```
126

127
**Usage Examples:**
128

129
```bash
130
# Check if Percy is running
131
percy ping
132
echo $?  # 0 if running, 1 if not
133

134
# Use in conditional scripts
135
if percy ping; then
136
  echo "Percy is running"
137
else
138
  echo "Percy is not running"
139
  percy start
140
fi
141
```
142

143
## Integration Patterns
144

145
### CI/CD Integration
146

147
```bash
148
# Basic CI workflow
149
percy exec -- npm test
150

151
# Parallel CI workflow (run across multiple machines)
152
percy exec --parallel -- npm test
153

154
# Partial builds (for matrix builds)
155
percy exec --partial -- npm run test:chrome
156
```
157

158
### Development Workflow
159

160
```bash
161
# Long development session
162
percy start
163

164
# Run tests multiple times during development
165
npm test
166
npm test
167
npm test
168

169
# Stop when done
170
percy stop
171
```
172

173
### Docker Integration
174

175
```bash
176
# In Dockerfile or docker-compose
177
ENV PERCY_TOKEN=your-token
178
RUN percy exec -- npm test
179
```
180

181
## Environment Variables
182

183
These environment variables are automatically set by Percy commands:
184

185
```bash { .api }
186
# Set by 'percy exec' and 'percy start'
187
PERCY_SERVER_ADDRESS           # Local Percy server URL (e.g., http://localhost:5338)
188
PERCY_BUILD_ID                 # Current build identifier
189
PERCY_BUILD_URL                # Percy dashboard URL for current build
190
PERCY_LOGLEVEL                 # Current logging level
191

192
# Configuration variables (can be set by user)
193
PERCY_PARALLEL_TOTAL           # Number of parallel processes (-1 for auto)
194
PERCY_PARALLEL_NONCE           # Unique identifier for parallel builds
195
PERCY_PARTIAL_BUILD            # Mark build as partial (1 to enable)
196
```
197

198
## Process Management
199

200
### Lifecycle
201

202
1. **Start Phase**: Percy initializes browser, creates build, starts server
203
2. **Execution Phase**: Tests run and capture snapshots via Percy server
204
3. **Stop Phase**: Percy uploads assets, finalizes build, cleans up resources
205

206
### Error Handling
207

208
```bash
209
# Percy exec handles errors gracefully
210
percy exec -- npm test
211
# If tests fail, Percy still finalizes the build properly
212

213
# Manual error handling with start/stop
214
percy start
215
if npm test; then
216
  echo "Tests passed"
217
else
218
  echo "Tests failed"
219
fi
220
percy stop  # Always finalize, regardless of test results
221
```
222

223
### Resource Cleanup
224

225
Percy automatically cleans up resources including:
226
- Browser processes
227
- Temporary files
228
- Network connections
229
- Background processes
230

231
If a process is interrupted, Percy attempts graceful cleanup. For stuck processes, you can force cleanup:
232

233
```bash
234
# Force cleanup (if percy stop hangs)
235
pkill -f percy
236
```