0
# Code Coverage
1

2
NYC code coverage wrapper for generating comprehensive test coverage reports with minimal configuration.
3

4
## Capabilities
5

6
### lb-nyc Command
7

8
Runs NYC (Istanbul) code coverage tool with passthrough support for all NYC options.
9

10
```typescript { .api }
11
/**
12
 * NYC code coverage function with full option passthrough
13
 * @param argv - Command line arguments including NYC options and target command
14
 * @param options - Execution options for dry run and process control
15
 * @returns ChildProcess when executed, string when dry run
16
 */
17
function nyc(argv: string[], options?: RunOptions): ChildProcess | string;
18
```
19

20
**CLI Usage:**
21

22
```bash
23
# Run tests with coverage
24
lb-nyc npm run mocha
25

26
# Run tests with coverage using lb-mocha
27
lb-nyc lb-mocha "dist/__tests__"
28

29
# Generate coverage report
30
lb-nyc report
31

32
# Generate HTML coverage report
33
lb-nyc report --reporter=html
34

35
# Generate LCOV report for CI
36
lb-nyc report --reporter=text-lcov
37

38
# Run with custom configuration
39
lb-nyc --include "dist/src/**" npm test
40
```
41

42
**Programmatic Usage:**
43

44
```typescript
45
import { nyc } from "@loopback/build";
46

47
// Run tests with coverage
48
const child = nyc(["npm", "run", "mocha"]);
49

50
// Dry run to see command
51
const command = nyc(["--reporter=html", "npm", "test"], { dryRun: true });
52
console.log(command); // Shows the NYC command that would be executed
53

54
// Run coverage in custom directory
55
nyc(["lb-mocha", "dist/__tests__"], { cwd: "/path/to/project" });
56
```
57

58
### Configuration Discovery
59

60
Automatically discovers NYC configuration files in the project.
61

62
**Configuration Search Order:**
63
1. `.nycrc` in project root
64
2. `.nycrc.json` in project root
65
3. `.nycrc.yaml` in project root
66
4. `.nycrc.yml` in project root
67
5. `nyc` section in `package.json`
68
6. Falls back to `@loopback/build/config/.nycrc`
69

70
**Default Configuration:**
71

72
```typescript { .api }
73
// @loopback/build/config/.nycrc contents:
74
interface NYCConfig {
75
  extension: [".js", ".ts"];    // File extensions to instrument
76
  reporter: ["html"];           // Coverage report format
77
  "exclude-after-remap": false; // Include remapped files in coverage
78
}
79
```
80

81
### Report Generation
82

83
Supports all NYC reporters and report generation options.
84

85
```typescript { .api }
86
interface NYCReporters {
87
  "text": string;         // Console text output
88
  "text-summary": string; // Brief console summary
89
  "html": string;         // HTML report in coverage/ directory
90
  "lcov": string;         // LCOV format for tools
91
  "json": string;         // JSON format
92
  "json-summary": string; // JSON summary
93
  "cobertura": string;    // Cobertura XML format
94
  "teamcity": string;     // TeamCity format
95
  "clover": string;       // Clover XML format
96
}
97
```
98

99
**Usage Examples:**
100

101
```bash
102
# Multiple reporters
103
lb-nyc --reporter=text --reporter=html npm test
104

105
# Custom output directory
106
lb-nyc --report-dir=./coverage-reports npm test
107

108
# Generate report from existing data
109
lb-nyc report --reporter=lcov
110
```
111

112
### Integration with Test Runners
113

114
Seamlessly integrates with various test runners and npm scripts.
115

116
**With Mocha:**
117

118
```bash
119
# Using lb-mocha
120
lb-nyc lb-mocha "dist/__tests__"
121

122
# Using npm script
123
lb-nyc npm run mocha
124

125
# Using standard mocha
126
lb-nyc ./node_modules/.bin/mocha "dist/__tests__"
127
```
128

129
**With Jest:**
130

131
```bash
132
# Using Jest
133
lb-nyc npm run jest
134

135
# Direct Jest execution
136
lb-nyc jest --coverage=false
137
```
138

139
### Coverage Thresholds
140

141
Supports coverage threshold enforcement.
142

143
```typescript { .api }
144
interface CoverageThresholds {
145
  "check-coverage": boolean;      // Enable threshold checking
146
  "lines": number;               // Line coverage threshold
147
  "functions": number;           // Function coverage threshold
148
  "branches": number;            // Branch coverage threshold
149
  "statements": number;          // Statement coverage threshold
150
}
151
```
152

153
**Usage:**
154

155
```bash
156
# Enforce 80% coverage
157
lb-nyc --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 npm test
158

159
# Per-file thresholds
160
lb-nyc --check-coverage --per-file --lines 80 npm test
161
```
162

163
### File Inclusion and Exclusion
164

165
Flexible file pattern support for coverage instrumentation.
166

167
```typescript { .api }
168
interface FilePatterns {
169
  "include": string[];    // Glob patterns for files to include
170
  "exclude": string[];    // Glob patterns for files to exclude
171
  "extension": string[];  // File extensions to instrument
172
}
173
```
174

175
**Common Patterns:**
176

177
```bash
178
# Include only source files
179
lb-nyc --include "src/**" --exclude "**/*.test.js" npm test
180

181
# Exclude test files and node_modules
182
lb-nyc --exclude "**/test/**" --exclude "**/node_modules/**" npm test
183

184
# Include TypeScript and JavaScript
185
lb-nyc --extension .js --extension .ts npm test
186
```
187

188
### Command Line Option Passthrough
189

190
All NYC command line options are supported and passed through.
191

192
```typescript { .api }
193
interface NYCOptions {
194
  "--reporter": string[];           // Coverage reporters to use
195
  "--report-dir": string;          // Output directory for reports
196
  "--temp-dir": string;            // Temporary directory for coverage data
197
  "--include": string[];           // Files to include in coverage
198
  "--exclude": string[];           // Files to exclude from coverage
199
  "--extension": string[];         // File extensions to instrument
200
  "--check-coverage": boolean;     // Enforce coverage thresholds
201
  "--lines": number;              // Line coverage threshold
202
  "--functions": number;          // Function coverage threshold
203
  "--branches": number;           // Branch coverage threshold
204
  "--statements": number;         // Statement coverage threshold
205
  "--per-file": boolean;          // Apply thresholds per file
206
  "--skip-full": boolean;         // Skip files with 100% coverage
207
  "--show-process-tree": boolean; // Show process tree
208
  "--instrument": boolean;        // Enable instrumentation
209
  "--source-map": boolean;        // Enable source map support
210
  "--produce-source-map": boolean; // Generate source maps
211
  "--all": boolean;               // Include all files in report
212
  "--cache": boolean;             // Enable instrumentation caching
213
  "--cache-dir": string;          // Cache directory location
214
}
215
```
216

217
### Usage Examples
218

219
**Basic Coverage:**
220

221
```typescript
222
import { nyc } from "@loopback/build";
223

224
// Run tests with coverage
225
nyc(["npm", "run", "test"], { dryRun: false });
226

227
// Generate HTML report
228
nyc(["report", "--reporter=html"], { dryRun: false });
229
```
230

231
**Package.json Integration:**
232

233
```json
234
{
235
  "scripts": {
236
    "test": "lb-mocha \"dist/__tests__\"",
237
    "test:coverage": "lb-nyc npm run test",
238
    "coverage": "npm run test:coverage && open coverage/index.html",
239
    "coverage:ci": "lb-nyc --reporter=text-lcov npm run test | coveralls"
240
  },
241
  "nyc": {
242
    "include": ["dist/src/**"],
243
    "exclude": ["dist/__tests__/"],
244
    "reporter": ["text", "html"],
245
    "check-coverage": true,
246
    "lines": 80,
247
    "functions": 80,
248
    "branches": 80,
249
    "statements": 80
250
  }
251
}
252
```
253

254
**Configuration File Examples:**
255

256
```json
257
// .nycrc
258
{
259
  "include": ["dist/src/**"],
260
  "exclude": [
261
    "dist/__tests__/",
262
    "**/*.d.ts"
263
  ],
264
  "extension": [".js", ".ts"],
265
  "reporter": ["text", "html", "lcov"],
266
  "check-coverage": true,
267
  "lines": 85,
268
  "functions": 85,
269
  "branches": 80,
270
  "statements": 85,
271
  "per-file": true,
272
  "all": true,
273
  "cache": true
274
}
275
```
276

277
### CI/CD Integration
278

279
Optimized for continuous integration and deployment workflows.
280

281
**Coverage Upload:**
282

283
```bash
284
# Generate LCOV for Coveralls
285
lb-nyc report --reporter=text-lcov | coveralls
286

287
# Generate for Codecov
288
lb-nyc report --reporter=lcovonly
289
codecov
290

291
# Generate for SonarQube
292
lb-nyc --reporter=lcov --reporter=text-lcov npm test
293
```
294

295
**Threshold Enforcement:**
296

297
```bash
298
# Fail build if coverage is below threshold
299
lb-nyc --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 npm test
300
```
301

302
### Error Handling
303

304
Proper error handling and reporting for coverage operations.
305

306
```typescript { .api }
307
// Threshold failures exit with non-zero code
308
// File pattern errors are reported with helpful messages
309
// Reporter errors show available reporter options
310
// Configuration errors provide clear guidance
311
```