-
Notifications
You must be signed in to change notification settings - Fork 531
/
developing.apt.vm
143 lines (105 loc) · 5.4 KB
/
developing.apt.vm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
------
Developing Surefire
------
Kristian Rosenvold
------
2011-03-07
------
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements. See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership. The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License. You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied. See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html
Developer Center
When working with Surefire, it is necessary to understand a few things:
* Multi-module Project
The plugin is built as part of a multi-module plugin. You need to check out
the complete module and build from there:
+---+
git clone https://gitbox.apache.org/repos/asf/maven-surefire.git
+---+
* Making Test Cases for Demonstrating Problems
When reporting an issue, it is immensely useful to create a small sample project
that demonstrates the problem. Surefire already contains a large number of such
projects, and they can be found at
{{surefire-its/src/test/resources/}}.
Typically you can check out one of the pre-existing projects and run it like this:
+---+
cd surefire-its/src/test/resources/failsafe-buildfail
mvn -Dsurefire.version=2.12 verify
+---+
* Attaching a Debugger
Sometimes it's appropriate to attach a remote debugger to the Surefire fork to try to determine what
is <really> going on. If you checkout and build trunk, you'd usually do something like this:
+---+
mvn -Dmaven.surefire.debug=true install
+---+
Load the source in your IDE, set a breakpoint at the start of <<<ForkedBooter#main>>> and attach
a debugger to port 5005.
* Tracing a Forked Execution
The forked Surefire process uses standard input and output to communicate back to the source. Sometimes when tracking troubles
it can be helpful to look at just the output of the fork.
This can be done by running:
+---+
mvn -e -X install | grep Forking
+---+
If you copy the command part of the output, you should be able to re-run the command by just pasting it on
the command line (you might have to do only the bits after <<<&&>>>).
You can now paste this command on the command line and capture the output of the fork. This may help you
determine if the problem is in the forked end or the receiving end.
When investigating a particular class, you probably want to <<<grep>>> the output for the class name.
Additionally the booter code (first field) can be seen at
{{https://git-wip-us.apache.org/repos/asf?p=maven-surefire.git;a=blob;f=surefire-api/src/main/java/org/apache/maven/surefire/booter/ForkingRunListener.java}}
The second field in the output (after the booter code) is the logical channel number, where different threads in the fork
should come in different channels.
* Test Cases
All patches to Surefire must contain test coverage, either as an integration test
or a unit test. All new features (changed/added plugin options) must be covered by
an end-to-end integration test.
There are
numerous other integration tests that all operate on small sample projects in
<<<surefire-its/src/test/resources>>>.
Example integration tests are <<<Surefire141PluggableProvidersIT>>> and the corresponding
<<<surefire-its/src/test/resources/surefire-141-pluggableproviders>>>.
* Essential Source Code Reading List
Some methods/classes reveal more about the basic working of a piece of code than others. The following classes/methods
are a "reading list" for getting quickly acquainted with the code:
+---+
AbstractSurefireMojo#executeAllProviders
ForkStarter#fork
ForkedBooter#main
+---+
* JDK Versions
The surefire booter is capable of booting all the way back to jdk1.8. Specifically
this means <<<surefire-api>>>, <<<surefire-booter>>>, <<<common-junit3>>>, <<<surefire-junit3>>>
and other modules are compiled with source/target 1.8.
* Provider Isolation
Classes in the SUT (<Subject Under Test>) override any classes within the
Surefire providers. This means providers using any
third party dependencies (other than the test framework itself) should
shade these classes to a different package.
* Common Provider Modules
The <<<surefire-providers>>> module contains <<<common-junitXX>>> modules. These modules
depend on the <<<XX>>> version of JUnit and can access the JUnit APIs at the correct
JUnit version level. Unit tests can also be written that will run with the
correct JUnit version. At build time, all of the relevant parts of these "common"
modules are just shaded into the provider jar files.
* Shadefire
"Shadefire" is the first module to be run in the
Surefire build. This creates a shaded version of the JUnit provider, and this provider
is thereafter used to build Surefire itself. This is
because the SUT overrides the provider, and the Shadefire provider has been
relocated to avoid this overriding when Surefire is building itself.