Skip to content

Commit 2f7fe87

Browse files
kgrytekgryte
committed
Document rules and add support for FAST_FAIL to test commands
1 parent 000e327 commit 2f7fe87

File tree

4 files changed

+475
-97
lines changed

4 files changed

+475
-97
lines changed

‎tools/make/lib/test/Makefile‎

Lines changed: 148 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -21,93 +21,201 @@
2121
include $(TOOLS_MAKE_LIB_DIR)/test/javascript.mk
2222

2323

24-
# TARGETS #
24+
# RULES #
2525

26-
# Run unit tests.
26+
#/
27+
# Runs unit tests.
2728
#
28-
# This target runs unit tests.
29-
29+
# ## Notes
30+
#
31+
# - This command is useful when wanting to glob for test files (e.g., run all tests for a particular package).
32+
#
33+
#
34+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`)
35+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
36+
#
37+
# @example
38+
# make test
39+
#
40+
# @example
41+
# make test TESTS_FILTER=".*/blas/base/dasum/.*"
42+
#/
3043
test: test-local
3144

3245
.PHONY: test
3346

34-
35-
# Run unit tests.
47+
#/
48+
# Runs a specified list of files containing unit tests.
3649
#
37-
# This target runs unit tests for a specified file set.
38-
50+
# ## Notes
51+
#
52+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
53+
#
54+
#
55+
# @param {string} FILES - list of test file paths
56+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
57+
#
58+
# @example
59+
# make test-files FILES='/foo/test.js /bar/test.js'
60+
#/
3961
test-files: test-files-local
4062

4163
.PHONY: test-files
4264

43-
44-
# Run unit tests locally.
65+
#/
66+
# Runs unit tests in the local environment.
4567
#
46-
# This target runs unit tests in a local environment.
47-
68+
# ## Notes
69+
#
70+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
71+
# - In this context, "local" refers to the local development environment, as opposed to running in a headless browser or on CI.
72+
#
73+
#
74+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`
75+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure)
76+
#
77+
# @example
78+
# make test-local
79+
#
80+
# @example
81+
# make test-local TESTS_FILTER=".*/blas/base/dasum/.*"
82+
#/
4883
test-local: test-javascript-local
4984

5085
.PHONY: test-local
5186

52-
53-
# Run unit tests locally.
87+
#/
88+
# Runs, in the local environment, a specified list of files containing unit tests.
5489
#
55-
# This target runs unit tests for a specified file set in a local environment.
56-
90+
# ## Notes
91+
#
92+
# - In this context, "local" refers to the local development environment, as opposed to running in a headless browser or on CI.
93+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
94+
#
95+
#
96+
# @param {string} FILES - list of test file paths
97+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
98+
#
99+
# @example
100+
# make test-files-local FILES='/foo/test.js /bar/test.js'
101+
#/
57102
test-files-local: test-javascript-files-local
58103

59104
.PHONY: test-files-local
60105

61-
62-
# Generate a test summary.
106+
#/
107+
# Runs unit tests and summarizes aggregated TAP output.
63108
#
64-
# This target runs unit tests and aggregates TAP output as a test summary.
65-
109+
# ## Notes
110+
#
111+
# - This command is useful when wanting to glob for test files (e.g., run all tests for a particular package).
112+
#
113+
#
114+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`)
115+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
116+
#
117+
# @example
118+
# make test-summary
119+
#
120+
# @example
121+
# make test-summary TESTS_FILTER=".*/blas/base/dasum/.*"
122+
#/
66123
test-summary: test-javascript-summary
67124

68125
.PHONY: test-summary
69126

70-
71-
# Generate a test summary.
127+
#/
128+
# Runs a specified list of files containing unit tests and summarizes aggregated TAP output.
72129
#
73-
# This target runs unit tests for a specified file set and aggregates TAP output as a test summary.
74-
130+
# ## Notes
131+
#
132+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
133+
#
134+
#
135+
# @param {string} FILES - list of test file paths
136+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
137+
#
138+
# @example
139+
# make test-files-summary FILES='/foo/test.js /bar/test.js'
140+
#/
75141
test-files-summary: test-javascript-files-summary
76142

77143
.PHONY: test-files-summary
78144

79-
80-
# Generate TAP output.
145+
#/
146+
# Runs unit tests and generates raw TAP output.
81147
#
82-
# This target runs unit tests and streams raw TAP output.
83-
148+
# ## Notes
149+
#
150+
# - This command is useful when wanting to glob for test files (e.g., run all tests for a particular package).
151+
#
152+
#
153+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`)
154+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
155+
#
156+
# @example
157+
# make test-tap
158+
#
159+
# @example
160+
# make test-tap TESTS_FILTER=".*/blas/base/dasum/.*"
161+
#/
84162
test-tap: test-javascript-tap
85163

86164
.PHONY: test-tap
87165

88-
89-
# Generate TAP output.
166+
#/
167+
# Runs a specified list of files containing unit tests and generates raw TAP output.
90168
#
91-
# This target runs unit tests for a specified file set and streams raw TAP output.
92-
169+
# ## Notes
170+
#
171+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
172+
#
173+
#
174+
# @param {string} FILES - list of test file paths
175+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
176+
#
177+
# @example
178+
# make test-files-tap FILES='/foo/test.js /bar/test.js'
179+
#/
93180
test-files-tap: test-javascript-files-tap
94181

95182
.PHONY: test-files-tap
96183

97-
98-
# Generate a xUnit XML.
184+
#/
185+
# Runs unit tests and converts TAP output to xUnit XML.
99186
#
100-
# This target runs unit tests and converts TAP output to xUnit XML.
101-
187+
# ## Notes
188+
#
189+
# - This command is useful when wanting to glob for test files (e.g., run all tests for a particular package).
190+
#
191+
#
192+
# @param {string} [TESTS_FILTER] - file path pattern (e.g., `.*/blas/base/dasum/.*`)
193+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
194+
#
195+
# @example
196+
# make test-xunit
197+
#
198+
# @example
199+
# make test-xunit TESTS_FILTER=".*/blas/base/dasum/.*"
200+
#/
102201
test-xunit: test-javascript-xunit
103202

104203
.PHONY: test-xunit
105204

106-
107-
# Generate a xUnit XML.
205+
#/
206+
# Runs a specified list of files containing unit tests and converts TAP output to xUnit XML.
108207
#
109-
# This target runs unit tests for a specified file set and converts TAP output to xUnit XML.
110-
208+
# ## Notes
209+
#
210+
# - This rule is useful when wanting to run a list of test files generated by some other command (e.g., a list of changed test files obtained via `git diff`).
211+
#
212+
#
213+
# @param {string} FILES - list of test file paths
214+
# @param {*} [FAST_FAIL] - flag indicating whether to stop running tests upon encountering a test failure
215+
#
216+
# @example
217+
# make test-files-xunit FILES='/foo/test.js /bar/test.js'
218+
#/
111219
test-files-xunit: test-javascript-files-xunit
112220

113221
.PHONY: test-files-xunit

‎tools/make/lib/test/README.md‎

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,71 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2022 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
121
# Tests
222

3-
> Tests recipes.
23+
> Test command.
424
525
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
626

727
<section class="intro">
828

9-
This directory contains [`make`][make] recipes for running project unit tests.
29+
This directory contains [`make`][make] rules for running project unit tests.
1030

1131
</section>
1232

1333
<!-- /.intro -->
1434

35+
<!-- Usage documentation. -->
36+
37+
<section class="usage">
38+
39+
## Usage
40+
41+
```text
42+
Usage: make <command> [<ENV_VAR>=<value> <ENV_VAR>=<value> ...]
43+
```
44+
45+
### Commands
46+
47+
#### test
48+
49+
Runs unit tests.
50+
51+
<!-- run-disable -->
52+
53+
```bash
54+
$ make test
55+
```
56+
57+
The command supports the following environment variables:
58+
59+
- **TESTS_FILTER**: file path pattern; e.g., `.*/blas/base/dasum/.*`.
60+
61+
The command supports the environment variables supported by the `test-local` command documented below.
62+
63+
This command is useful when wanting to glob for test files (e.g., run all tests for a particular package).
64+
65+
</section>
66+
67+
<!-- /.usage -->
68+
1569
<!-- Section to include notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
1670

1771
<section class="notes">

0 commit comments

Comments
 (0)