0
# Built-in Tasks
1

2
Buidler includes a comprehensive set of built-in tasks for common development workflows including compilation, testing, project management, and debugging. These tasks form the foundation of the Buidler development experience.
3

4
## Capabilities
5

6
### Core Task Names
7

8
Reference for all built-in task and subtask names. Note: These constants are not exported from the public API, but the string values can be used directly.
9

10
```typescript
11
// Main tasks
12
"check"
13
"clean"
14
"compile"
15
"console"
16
"flatten"
17
"help"
18
"run"
19
"test"
20

21
// Compilation subtasks
22
"compile:get-source-paths"
23
"compile:get-resolved-sources"
24
"compile:get-dependency-graph"
25
"compile:get-compiler-input"
26
"compile:run-compiler"
27
"compile:compile"
28
"compile:cache"
29
"compile:build-artifacts"
30

31
// Flatten subtasks
32
"flatten:get-flattened-sources"
33

34
// Test subtasks
35
"test:run-mocha-tests"
36
"test:get-test-files"
37
"test:setup-test-environment"
38
```
39

40
### Clean Task
41

42
Removes compilation artifacts and cache to ensure clean builds.
43

44
```typescript { .api }
45
// Task: clean
46
// Description: "Clears the cache and deletes all artifacts"
47
// Parameters: None
48
```
49

50
**Usage Examples:**
51

52
```bash
53
# Clean all artifacts and cache
54
buidler clean
55

56
# Clean before compile in another task
57
await hre.run("clean");
58
```
59

60
### Compile Task
61

62
Compiles all Solidity contracts and generates artifacts with dependency resolution and caching.
63

64
```typescript { .api }
65
// Task: compile
66
// Description: "Compiles the entire project, building all artifacts"
67
// Parameters:
68
//   --force: boolean - Force compilation ignoring cache
69

70
// Subtasks involved in compilation:
71
// 1. compile:get-source-paths - Find all Solidity source files
72
// 2. compile:get-resolved-sources - Resolve imports and dependencies
73
// 3. compile:get-dependency-graph - Build contract dependency graph
74
// 4. compile:get-compiler-input - Generate solc input JSON
75
// 5. compile:run-compiler - Execute Solidity compiler
76
// 6. compile:compile - Process compiler output
77
// 7. compile:cache - Update compilation cache
78
// 8. compile:build-artifacts - Generate final artifacts
79
```
80

81
**Usage Examples:**
82

83
```bash
84
# Compile all contracts
85
buidler compile
86

87
# Force full recompilation (ignore cache)
88
buidler compile --force
89

90
# Compile programmatically
91
await hre.run("compile");
92
await hre.run("compile", { force: true });
93
```
94

95
### Console Task
96

97
Opens an interactive Node.js REPL with the Buidler runtime environment loaded.
98

99
```typescript { .api }
100
// Task: console
101
// Description: "Opens a buidler console"
102
// Parameters:
103
//   --noCompile: boolean - Don't compile before running this task
104
```
105

106
**Usage Examples:**
107

108
```bash
109
# Open console (compiles first)
110
buidler console
111

112
# Open console without compiling
113
buidler console --noCompile
114

115
# In the console, access runtime environment
116
> const accounts = await web3.eth.getAccounts()
117
> const balance = await web3.eth.getBalance(accounts[0])
118
> console.log(balance)
119
```
120

121
### Run Task
122

123
Executes user-defined JavaScript or TypeScript scripts within the Buidler environment.
124

125
```typescript { .api }
126
// Task: run
127
// Description: "Runs a user-defined script after compiling the project"
128
// Parameters:
129
//   script: string (positional) - A js file to be run within buidler's environment
130
//   --noCompile: boolean - Don't compile before running this task
131
```
132

133
**Usage Examples:**
134

135
```bash
136
# Run a deployment script
137
buidler run scripts/deploy.js
138

139
# Run script without compiling first
140
buidler run scripts/quick-task.js --noCompile
141

142
# Run TypeScript script
143
buidler run scripts/deploy.ts
144
```
145

146
**Example script (scripts/deploy.js):**
147

148
```javascript
149
// Script has access to Buidler runtime environment
150
async function main() {
151
  const accounts = await web3.eth.getAccounts();
152
  console.log("Deploying from account:", accounts[0]);
153
  
154
  // Access artifacts
155
  const ContractArtifact = await artifacts.readArtifact("MyContract");
156
  console.log("Contract ABI:", ContractArtifact.abi);
157
  
158
  // Deploy contract logic here
159
}
160

161
main()
162
  .then(() => process.exit(0))
163
  .catch((error) => {
164
    console.error(error);
165
    process.exit(1);
166
  });
167
```
168

169
### Test Task
170

171
Runs the project's test suite using Mocha with Buidler environment integration.
172

173
```typescript { .api }
174
// Task: test
175
// Description: "Runs mocha tests"
176
// Parameters:
177
//   testFiles: string[] (variadic positional) - An optional list of files to test
178
//   --noCompile: boolean - Don't compile before running this task
179

180
// Subtasks:
181
// 1. test:setup-test-environment - Configure test environment
182
// 2. test:get-test-files - Find test files to execute
183
// 3. test:run-mocha-tests - Execute Mocha test suite
184
```
185

186
**Usage Examples:**
187

188
```bash
189
# Run all tests
190
buidler test
191

192
# Run specific test files
193
buidler test test/MyContract.test.js test/Utils.test.js
194

195
# Run tests without compiling
196
buidler test --noCompile
197

198
# Run tests programmatically
199
await hre.run("test");
200
await hre.run("test", { testFiles: ["test/specific.test.js"] });
201
```
202

203
**Example test file:**
204

205
```javascript
206
// test/MyContract.test.js
207
const { expect } = require("chai");
208

209
describe("MyContract", function() {
210
  beforeEach(async function() {
211
    // Setup runs with Buidler environment
212
    this.accounts = await web3.eth.getAccounts();
213
    
214
    const ContractFactory = await artifacts.readArtifact("MyContract");
215
    // Deploy contract logic
216
  });
217
  
218
  it("should work correctly", async function() {
219
    // Test implementation
220
    expect(true).to.be.true;
221
  });
222
});
223
```
224

225
### Help Task
226

227
Displays help information about available tasks and their parameters.
228

229
```typescript { .api }
230
// Task: help
231
// Description: "Prints help message"
232
// Parameters:
233
//   task: string (optional positional) - An optional task to print more info about
234
```
235

236
**Usage Examples:**
237

238
```bash
239
# Show general help
240
buidler help
241

242
# Show help for specific task
243
buidler help compile
244
buidler help test
245

246
# Show all available tasks
247
buidler
248
```
249

250
### Flatten Task
251

252
Combines all contract files and their dependencies into a single flattened file for verification.
253

254
```typescript { .api }
255
// Task: flatten
256
// Description: "Flattens and prints all contracts and their dependencies"
257
// Parameters: None
258

259
// Subtask:
260
// flatten:get-flattened-sources - Process and combine source files
261
```
262

263
**Usage Examples:**
264

265
```bash
266
# Flatten all contracts to stdout
267
buidler flatten
268

269
# Save flattened output to file
270
buidler flatten > flattened.sol
271

272
# Use in verification workflows
273
buidler flatten | pbcopy  # Copy to clipboard on macOS
274
```
275

276
### Check Task
277

278
Placeholder task for custom validation and checking logic.
279

280
```typescript { .api }
281
// Task: check
282
// Description: "Check whatever you need"
283
// Parameters: None
284
// Action: Empty (intended for user override)
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
// Override check task for custom validation
291
task("check", "Run custom project checks", async (taskArgs, hre) => {
292
  console.log("Running custom checks...");
293
  
294
  // Custom validation logic
295
  const hasReadme = fs.existsSync("README.md");
296
  if (!hasReadme) {
297
    throw new Error("README.md is missing");
298
  }
299
  
300
  // Check contract compilation
301
  await hre.run("compile");
302
  
303
  // Lint checks
304
  await exec("npm run lint");
305
  
306
  console.log("All checks passed!");
307
});
308
```
309

310
### Subtask Usage
311

312
Access and customize individual subtasks for advanced workflows.
313

314
**Usage Examples:**
315

316
```typescript
317
// Get source file paths
318
task("list-sources", async (taskArgs, hre) => {
319
  const sources = await hre.run("compile:get-source-paths");
320
  console.log("Source files:", sources);
321
});
322

323
// Custom compilation workflow
324
task("custom-compile", async (taskArgs, hre) => {
325
  const sources = await hre.run("compile:get-source-paths");
326
  const resolvedSources = await hre.run("compile:get-resolved-sources", { sources });
327
  
328
  // Custom processing of resolved sources
329
  console.log("Processing", resolvedSources.length, "contracts");
330
  
331
  // Continue with normal compilation
332
  await hre.run("compile:compile", { resolvedSources });
333
});
334

335
// Override test file discovery
336
internalTask("test:get-test-files", async (taskArgs, hre) => {
337
  // Custom test file discovery logic
338
  return glob.sync("test/**/*.spec.js");
339
});
340
```
341

342
### Task Chaining and Dependencies
343

344
Built-in tasks are designed to be composable and chainable.
345

346
**Usage Examples:**
347

348
```typescript
349
// Custom workflow task
350
task("deploy", "Build and deploy contracts", async (taskArgs, hre) => {
351
  // Clean and compile
352
  await hre.run("clean");
353
  await hre.run("compile");
354
  
355
  // Run tests before deployment
356
  await hre.run("test");
357
  
358
  // Custom deployment logic
359
  console.log("Deploying contracts...");
360
  // Deployment implementation
361
});
362

363
// Development workflow
364
task("dev", "Full development cycle", async (taskArgs, hre) => {
365
  await hre.run("clean");
366
  await hre.run("compile");
367
  await hre.run("test");
368
  await hre.run("check");
369
  
370
  console.log("Development cycle complete!");
371
});
372
```
373

374
### Task Parameter Access
375

376
All built-in tasks can be called programmatically with parameters.
377

378
```typescript { .api }
379
// Run tasks with parameters
380
await hre.run("compile", { force: true });
381
await hre.run("test", { 
382
  testFiles: ["test/unit/", "test/integration/"],
383
  noCompile: false 
384
});
385
await hre.run("run", { 
386
  script: "scripts/deploy.js",
387
  noCompile: false 
388
});
389
await hre.run("console", { noCompile: true });
390
```