Skip to content

Commit deee50f

Browse files
kgrytekgryte
committed
Document rules
1 parent 2b664a2 commit deee50f

File tree

1 file changed

+79
-28
lines changed

1 file changed

+79
-28
lines changed

‎tools/make/lib/test-cov/istanbul.mk‎

Lines changed: 79 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,17 @@ ifneq ($(OS), Darwin)
3737
endif
3838

3939
# Define the executable for generating a coverage report name:
40-
COVERAGE_REPORT_NAME ?= $(TOOLS_DIR)/test-cov/scripts/coverage_report_name
40+
COVERAGE_REPORT_NAME ?= $(TOOLS_DIR)/test-cov/scripts/istanbul_coverage_report_name
4141

4242
# Define the path to the Istanbul executable.
4343
#
44-
# To install Istanbul:
44+
# ## Notes
4545
#
46-
# ```bash
47-
# $ npm install istanbul
48-
# ```
46+
# - To install Istanbul:
47+
#
48+
# ```bash
49+
# $ npm install istanbul@0.4.5
50+
# ```
4951
#
5052
# [1]: https://github.com/gotwarlost/istanbul
5153
ISTANBUL ?= $(BIN_DIR)/istanbul
@@ -123,19 +125,36 @@ endif
123125

124126
# FUNCTIONS #
125127

128+
#/
126129
# Macro to retrieve a list of test directories for Istanbul instrumented source code.
127130
#
131+
# @private
132+
#
133+
# @example
128134
# $(call get-istanbul-test-dirs)
129-
135+
#/
130136
get-istanbul-test-dirs = $(shell find $(find_kernel_prefix) $(ISTANBUL_INSTRUMENT_OUT) $(FIND_ISTANBUL_TEST_DIRS_FLAGS))
131137

132138

133-
# TARGETS #
139+
# RULES #
134140

141+
#/
135142
# Instruments source code.
136143
#
137-
# This target instruments source code.
138-
144+
# ## Notes
145+
#
146+
# - This recipe does the following:
147+
#
148+
# 1. Instruments all package source files and writes the instrumented files to a specified directory (e.g., a `build` directory).
149+
# 2. Copies all non-instrumented package files to the instrumentation directory. This is necessary as files such as `*.json` files are not instrumented, and thus, the files are not copied over by Istanbul.
150+
#
151+
# In short, we need to effectively recreate the project source tree in the instrumentation directory in order for tests to properly run.
152+
#
153+
# @private
154+
#
155+
# @example
156+
# make test-istanbul-instrument
157+
#/
139158
test-istanbul-instrument: $(NODE_MODULES) clean-istanbul-instrument
140159
$(QUIET) $(MKDIR_RECURSIVE) $(ISTANBUL_INSTRUMENT_OUT)
141160
$(QUIET) $(ISTANBUL_INSTRUMENT) $(ISTANBUL_INSTRUMENT_FLAGS) $(SRC_DIR)
@@ -146,11 +165,26 @@ test-istanbul-instrument: $(NODE_MODULES) clean-istanbul-instrument
146165

147166
.PHONY: test-istanbul-instrument
148167

149-
150-
# Run unit tests and generate a test coverage report.
168+
#/
169+
# Runs unit tests and generates a test coverage report.
151170
#
152-
# This target instruments source code, runs unit tests, and outputs a test coverage report.
153-
171+
# ## Notes
172+
#
173+
# - Raw TAP output is piped to a TAP reporter.
174+
# - This command is useful when wanting to glob for JavaScript test files (e.g., generate a test coverage report for all JavaScript tests for a particular package).
175+
#
176+
#
177+
# @private
178+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`)
179+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
180+
#
181+
#
182+
# @example
183+
# make test-istanbul
184+
#
185+
# @example
186+
# make test-istanbul TESTS_FILTER=".*/blas/base/dasum/.*"
187+
#/
154188
test-istanbul: $(NODE_MODULES) test-istanbul-instrument
155189
$(QUIET) $(MKDIR_RECURSIVE) $(COVERAGE_DIR)
156190
$(QUIET) $(MAKE_EXECUTABLE) $(COVERAGE_REPORT_NAME)
@@ -171,43 +205,60 @@ test-istanbul: $(NODE_MODULES) test-istanbul-instrument
171205

172206
.PHONY: test-istanbul
173207

174-
175-
# Generate a test coverage report.
208+
#/
209+
# Generates a single test coverage report from one or more JSON coverage files.
176210
#
177-
# This target generates a test coverage report from JSON coverage files.
178-
211+
# @private
212+
#
213+
# @example
214+
# make test-istanbul-report
215+
#/
179216
test-istanbul-report: $(NODE_MODULES)
180217
$(QUIET) $(ISTANBUL_REPORT) $(ISTANBUL_REPORT_FLAGS) $(ISTANBUL_REPORT_FORMAT)
181218

182219
.PHONY: test-istanbul-report
183220

184-
185-
# Run unit tests and generate a test coverage report.
221+
#/
222+
# Runs unit tests and generates a test coverage report.
186223
#
187-
# This target instruments source code, runs unit tests, and outputs a test coverage report.
188-
224+
# ## Notes
225+
#
226+
# - This recipe implements the "classic" approach for using Istanbul to generate a code coverage report using the `cover` command. For certain situations, this recipe can still be used, but, in general, when using Istanbul, we instrument, backfill package files, and generate a coverage report from the instrumentation directory.
227+
#
228+
# @private
229+
#
230+
# @example
231+
# make test-istanbul-cover
232+
#/
189233
test-istanbul-cover: $(NODE_MODULES)
190234
$(QUIET) NODE_ENV="$(NODE_ENV_TEST)" \
191235
NODE_PATH="$(NODE_PATH_TEST)" \
236+
TEST_MODE=coverage \
192237
$(ISTANBUL_COVER) $(ISTANBUL_COVER_FLAGS) $(JAVASCRIPT_TEST) -- $(JAVASCRIPT_TEST_FLAGS) $(TESTS)
193238

194239
.PHONY: test-istanbul-cover
195240

196-
197-
# View a test coverage report.
241+
#/
242+
# Opens an HTML test coverage report in a local web browser.
198243
#
199-
# This target opens an HTML coverage report in a local web browser.
200-
244+
# @private
245+
#
246+
# @example
247+
# make view-istanbul-report
248+
#/
201249
view-istanbul-report:
202250
$(QUIET) $(OPEN) $(ISTANBUL_HTML_REPORT)
203251

204252
.PHONY: view-istanbul-report
205253

206-
254+
#/
207255
# Removes instrumented files.
208256
#
209-
# This targets removes previously instrumented files by removing the instrumented source code directory entirely.
210-
257+
# @private
258+
#
259+
# @example
260+
# make clean-istanbul-instrument
261+
#/
211262
clean-istanbul-instrument:
212263
$(QUIET) $(DELETE) $(DELETE_FLAGS) $(COVERAGE_INSTRUMENTATION_DIR)
213264

0 commit comments

Comments
 (0)