@@ -58,6 +58,7 @@ instrumentation ->
58
58
build.gradle.kts
59
59
testing
60
60
build.gradle.kts
61
+ metadata.yaml
61
62
```
62
63
63
64
The top level ` settings.gradle.kts ` file would contain the following (please add in alphabetical order):
@@ -68,6 +69,15 @@ include("instrumentation:yarpc-1.0:library")
68
69
include(" instrumentation:yarpc-1.0:testing" )
69
70
```
70
71
72
+ ### Instrumentation metadata.yaml (Experimental)
73
+
74
+ Each module can contain a ` metadata.yaml ` file that describes the instrumentation. This information
75
+ is then used when generating the [ instrumentation-list.yaml] ( ../instrumentation-list.yaml ) file.
76
+ The schema for ` metadata.yaml ` is still in development and may change in the future. See the
77
+ [ instrumentation-docs readme] ( ../../instrumentation-docs/readme.md ) for more information and the
78
+ latest schema.
79
+
80
+
71
81
### Instrumentation Submodules
72
82
73
83
When writing instrumentation that requires submodules for different versions, the name of each
@@ -215,10 +225,10 @@ library instrumentation test, there will be code calling into the instrumentatio
215
225
javaagent instrumentation test it will generally use the underlying library API as is and just rely
216
226
on the javaagent to apply all the necessary bytecode changes automatically.
217
227
218
- You can use either JUnit 5 (recommended) or Spock to test the instrumentation. Start by creating an
219
- abstract class with an abstract method, for example ` configure() ` , that returns the instrumented
220
- object, such as a client, server, or the main class of the instrumented library. Then, depending on
221
- the chosen test library, go to the [ JUnit ] ( #junit ) or [ Spock ] ( #spock ) section .
228
+ You can use JUnit 5 to test the instrumentation. Start by creating an abstract class with an
229
+ abstract method, for example ` configure() ` , that returns the instrumented object, such as a client,
230
+ server, or the main class of the instrumented library. See the [ JUnit ] ( #junit ) section for more
231
+ information .
222
232
223
233
After writing some tests, return to the ` library ` package and make sure it has
224
234
a ` testImplementation ` dependency on the ` testing ` submodule. Then, create a test class that extends
@@ -281,37 +291,6 @@ You can use the `@RegisterExtension` annotation to make sure that the instrument
281
291
picked up by JUnit. Then, return the same extension instance in the ` testing() ` method
282
292
implementation so that it's used in all test scenarios implemented in the abstract class.
283
293
284
- ### Spock
285
-
286
- The ` testing-common ` module contains some utilities that facilitate writing Spock instrumentation
287
- tests, such as the ` InstrumentationSpecification ` base class and the ` LibraryTestTrait `
288
- and ` AgentTestTrait ` traits.
289
-
290
- Consider the following abstract test class extending ` InstrumentationSpecification ` :
291
-
292
- ``` groovy
293
- abstract class AbstractYarpcTest extends InstrumentationSpecification {
294
-
295
- abstract Yarpc configure(Yarpc yarpc);
296
-
297
- def "test something"() {
298
- // ...
299
- }
300
- }
301
- ```
302
-
303
- The ` InstrumentationSpecification ` class contains abstract methods that are implemented by one of
304
- our test traits in the actual test class. For example:
305
-
306
- ``` groovy
307
- class LibraryYarpcTest extends AbstractYarpcTest implements LibraryTestTrait {
308
-
309
- @Override
310
- Yarpc configure(Yarpc yarpc) {
311
- // register interceptor/listener etc
312
- }
313
- }
314
- ```
315
294
316
295
## Writing Java agent instrumentation
317
296
@@ -352,9 +331,8 @@ without the user knowing about the instrumentation.
352
331
353
332
Create a test that extends the base class you wrote earlier but does nothing in the ` configure() `
354
333
method. Unlike the library instrumentation, the javaagent instrumentation is supposed to work
355
- without any explicit user code modification. Depending on the testing framework, either use
356
- the ` AgentInstrumentationExtension ` or implement the ` AgentTestingTrait ` , and try running tests in
357
- this class. All tests should pass.
334
+ without any explicit user code modification. Add an ` AgentInstrumentationExtension ` and try running
335
+ tests in this class. All tests should pass.
358
336
359
337
Note that all the tests inside the ` javaagent ` module are run using the ` agent-for-testing `
360
338
javaagent, with the instrumentation being loaded as an extension. This is done to perform the same
0 commit comments