You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Simple parallel test runner for Julia tests with autodiscovery.
4
7
5
8
## Usage
@@ -40,102 +43,9 @@ using ParallelTestRunner
40
43
runtests(MyModule, ARGS)
41
44
```
42
45
43
-
### Customizing the test suite
44
-
45
-
By default, `runtests` automatically discovers all `.jl` files in your `test/` directory (excluding `runtests.jl` itself) using the `find_tests` function. You can customize which tests to run by providing a custom `testsuite` dictionary:
46
-
47
-
```julia
48
-
# Manually define your test suite
49
-
testsuite =Dict(
50
-
"basic"=>quote
51
-
include("basic.jl")
52
-
end,
53
-
"advanced"=>quote
54
-
include("advanced.jl")
55
-
end
56
-
)
57
-
58
-
runtests(MyModule, ARGS; testsuite)
59
-
```
60
-
61
-
You can also use `find_tests` to automatically discover tests and then filter or modify them. This requires manually parsing arguments so that filtering is only applied when the user did not request specific tests to run:
62
-
63
-
```julia
64
-
# Start with autodiscovered tests
65
-
testsuite =find_tests(pwd())
66
-
67
-
# Parse arguments
68
-
args =parse_args(ARGS)
69
-
70
-
iffilter_tests!(testsuite, args)
71
-
# Remove tests that shouldn't run on Windows
72
-
if Sys.iswindows()
73
-
delete!(testsuite, "ext/specialfunctions")
74
-
end
75
-
end
76
-
77
-
runtests(MyModule, args; testsuite)
78
-
```
79
-
80
-
### Provide defaults
81
-
82
-
`runtests` takes a keyword argument that one can use to provide default definitions to be loaded before each testfile.
83
-
As an example one could always load `Test` and the package under test.
84
-
85
-
```julia
86
-
const init_code =quote
87
-
using Test
88
-
using MyPackage
89
-
end
90
-
91
-
runtests(MyModule, ARGS; init_code)
92
-
```
93
-
94
-
### Interactive use
95
-
96
-
Arguments can also be passed via the standard `Pkg.test` interface for interactive control. For example, here is how we could run the subset of tests that start with the testset name "MyTestsetA" in i) verbose mode, and ii) with default threading enabled:
97
-
98
-
```julia-repl
99
-
# In an environment where `MyPackage.jl` is available
100
-
julia --proj
101
-
102
-
julia> using Pkg
103
-
104
-
# No need to start a fresh session to change threading
There are a few packages already using `ParallelTestRunner.jl` to parallelize their tests, you can look at their setups if you need inspiration to move your packages as well:
Copy file name to clipboardExpand all lines: docs/src/advanced.md
+51-21Lines changed: 51 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,13 +9,12 @@ end
9
9
10
10
This page covers advanced features of `ParallelTestRunner` for customizing test execution.
11
11
12
-
## Custom Test Suites
12
+
## Customizing the test suite
13
13
14
-
By default, `runtests` automatically discovers all `.jl` files in your test directory. You can provide a custom test suite dictionary to have full control over which tests run:
14
+
By default, [`runtests`](@ref) automatically discovers all `.jl` files in your `test/` directory (excluding `runtests.jl` itself) using the `find_tests` function.
15
+
You can customize which tests to run by providing a custom `testsuite` dictionary:
15
16
16
17
```julia
17
-
using ParallelTestRunner
18
-
19
18
# Manually define your test suite
20
19
testsuite =Dict(
21
20
"basic"=>quote
@@ -26,43 +25,39 @@ testsuite = Dict(
26
25
end
27
26
)
28
27
29
-
runtests(MyPackage, ARGS; testsuite)
28
+
runtests(MyModule, ARGS; testsuite)
30
29
```
31
30
32
-
Each value in the dictionary should be an expression (use `quote...end`) that executes the test code.
33
-
34
-
## Filtering Tests
31
+
## Filtering Test Files
35
32
36
-
You can use `find_tests` to automatically discover tests and then filter or modify them:
33
+
You can also use [`find_tests`](@ref) to automatically discover tests and then filter or modify them.
34
+
This requires manually parsing arguments so that filtering is only applied when the user did not request specific tests to run:
37
35
38
36
```julia
39
-
using ParallelTestRunner
40
-
41
37
# Start with autodiscovered tests
42
38
testsuite =find_tests(pwd())
43
39
44
-
# Parse arguments manually
40
+
# Parse arguments
45
41
args =parse_args(ARGS)
46
42
47
-
# Filter based on arguments
48
43
iffilter_tests!(testsuite, args)
49
-
# Additional filtering is allowed
50
-
# For example, remove platform-specific tests
44
+
# Remove tests that shouldn't run on Windows
51
45
if Sys.iswindows()
52
-
delete!(testsuite, "unix_only_test")
46
+
delete!(testsuite, "ext/specialfunctions")
53
47
end
54
48
end
55
49
56
-
runtests(MyPackage, args; testsuite)
50
+
runtests(MyModule, args; testsuite)
57
51
```
58
52
59
-
The `filter_tests!` function returns `true` if no positional arguments were provided (allowing additional filtering) and `false` if the user specified specific tests (preventing further filtering).
53
+
The [`filter_tests!`](@ref) function returns `true` if no positional arguments were provided (allowing additional filtering) and `false` if the user specified specific tests (preventing further filtering).
60
54
61
55
## Initialization Code
62
56
63
-
Use the `init_code` keyword argument to provide code that runs before each test file. This is useful for:
57
+
Use the `init_code` keyword argument to [`runtests`](@ref) to provide code that runs before each test file.
58
+
This is useful for:
64
59
- Importing packages
65
-
- Defining constants or helper functions
60
+
- Defining constants, defaults or helper functions
Workers created this way can be used with the `test_worker` function or for other distributed computing tasks.
182
177
178
+
### Interactive use
179
+
180
+
Arguments can also be passed via the standard `Pkg.test` interface for interactive control. For example, here is how we could run the subset of tests that start with the testset name "MyTestsetA" in i) verbose mode, and ii) with default threading enabled:
181
+
182
+
```julia-repl
183
+
# In an environment where `MyPackage.jl` is available
184
+
julia --proj
185
+
186
+
julia> using Pkg
187
+
188
+
# No need to start a fresh session to change threading
@@ -126,8 +126,6 @@ Press `Ctrl+C` to interrupt the test run. The framework will:
126
126
- Display a summary of completed tests
127
127
- Exit gracefully
128
128
129
-
You can also press `?` during execution to see which tests are currently running.
130
-
131
129
## Test File Structure
132
130
133
131
Your test files should be standard Julia test files using the `Test` standard library:
@@ -143,3 +141,20 @@ end
143
141
```
144
142
145
143
Each test file runs in its own isolated module, so you don't need to worry about test pollution between files.
144
+
145
+
## Packages using ParallelTestRunner.jl
146
+
147
+
There are a few packages already [using `ParallelTestRunner.jl`](https://github.com/search?q=%22using+ParallelTestRunner%22+language%3AJulia++NOT+is%3Aarchived+NOT+is%3Afork&type=code) to parallelize their tests, you can look at their setups if you need inspiration to move your packages as well:
0 commit comments