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
Copy file name to clipboardExpand all lines: docs/DevelopmentGuide.md
+53-48Lines changed: 53 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ This guide covers some of the common how-tos and technical reference material fo
19
19
20
20
The trace library uses Docker Compose to create a Ruby environment to develop and test within, as well as containers for any dependencies that might be necessary for certain kinds of tests.
21
21
22
-
To start a development environment, choose a target Ruby version then run the following:
22
+
To start a development environment, choose a target Ruby or JRuby version. Then run the following:
23
23
24
24
```bash
25
25
# In the root directory of the project...
@@ -28,12 +28,15 @@ cd ~/dd-trace-rb
28
28
# Create and start a Ruby 3.3 test environment with its dependencies
29
29
docker compose run --rm tracer-3.3 /bin/bash
30
30
31
+
# or a JRuby test environment with its dependencies
32
+
docker compose run --rm tracer-jruby-9.4 /bin/bash
33
+
31
34
# Then inside the container (e.g. `root@2a73c6d8673e:/app`)...
32
35
# Install the library dependencies
33
36
bundle install
34
37
```
35
38
36
-
Then within this container you can [run tests](#running-tests), or [run code quality checks](#checking-code-quality).
39
+
Within this container, you can [run tests](#running-tests) or [run code quality checks](#checking-code-quality).
37
40
38
41
## Testing
39
42
@@ -43,7 +46,7 @@ The test suite uses [RSpec](https://rspec.info/) tests to verify the correctness
43
46
44
47
New tests should be written as RSpec tests in the `spec/datadog` folder. Test files should generally mirror the structure of `lib`.
45
48
46
-
All changes should be covered by a corresponding RSpec tests. Unit tests are preferred, and integration tests are accepted where appropriate (e.g. acceptance tests, verifying compatibility with datastores, etc) but should be kept to a minimum.
49
+
All changes should be covered by corresponding RSpec tests. Unit tests are preferred, and integration tests are accepted where appropriate (e.g. acceptance tests, verifying compatibility with datastores, etc) but should be kept to a minimum.
47
50
48
51
### Running tests
49
52
@@ -54,31 +57,31 @@ Any file that is **not** inside a `contrib` folder is part of the core library.
54
57
You can run all the tests for the core library with:
55
58
56
59
```
57
-
$ bundle exec rake test:main
60
+
bundle exec rake test:main
58
61
```
59
62
60
63
##### Specific core tests
61
64
62
65
You can also run only a subset of the core library tests.
63
66
64
-
For example, for the test files [utils_spec.rb](https://github.com/DataDog/dd-trace-rb/blob/d66a6688f6cddab6a8c3cb1d6e0a6bfe86928e44/spec/datadog/core/utils_spec.rb) and
67
+
For example, for the test files [utils_spec.rb](https://github.com/DataDog/dd-trace-rb/blob/d66a6688f6cddab6a8c3cb1d6e0a6bfe86928e44/spec/datadog/core/utils_spec.rb) and
65
68
[error_spec.rb](https://github.com/DataDog/dd-trace-rb/blob/d66a6688f6cddab6a8c3cb1d6e0a6bfe86928e44/spec/datadog/core/error_spec.rb), you can run:
`bundle exec rake ci` will run the entire test suite with any given Ruby runtime, just as CI does.
81
-
However, this is not recommended because it is going take a long time.
84
+
However, this is not recommended because it will take a long time.
82
85
83
86
Instead, run [specific core tests](#specific-core-tests), [integation tests](#for-integrations), or [the core library tests](#for-the-core-library).
84
87
@@ -90,9 +93,9 @@ Any file that **is** inside a `contrib` folder is part of an integration.
90
93
91
94
To get a list of the test tasks, run `bundle exec rake -T test:`
92
95
93
-
To run test, run `bundle exec rake test:<spec_name>`
96
+
To run a test, run `bundle exec rake test:<spec_name>`
94
97
95
-
Take `bundle exec rake test:redis` as example, multiple versions of `redis` from different dependency definitions are being tested (from `Matrixfile`).
98
+
Take `bundle exec rake test:redis` as example: multiple versions of `redis` from different dependency definitions are being tested (from `Matrixfile`).
96
99
97
100
98
101
```ruby
@@ -105,7 +108,7 @@ Take `bundle exec rake test:redis` as example, multiple versions of `redis` from
105
108
}
106
109
```
107
110
108
-
If the dependency groups are prepared (with up-to-date gemfile and lockfile), the test task would install them before running the test.
111
+
If the dependency groups are prepared (with up-to-date gemfile and lockfile), the test task will install them before running the test.
109
112
110
113
**Working with different dependencies**
111
114
@@ -117,39 +120,39 @@ You can find them by running the following command:
117
120
bundle exec rake -T dependency:
118
121
```
119
122
120
-
Dependency group definitions are located under `appraisal/` directory using the same DSL provided by [Appraisal](https://github.com/thoughtbot/appraisal). These definitions are used to generate `gemfiles/*.gemfile` and then `gemfiles/*.lock`. All the files are underscored and prefixed with Ruby runtime.
123
+
Dependency group definitions are located under the `appraisal/` directory using the same DSL provided by [Appraisal](https://github.com/thoughtbot/appraisal). These definitions are used to generate `gemfiles/*.gemfile` and then `gemfiles/*.lock`. All the files are underscored and prefixed with the Ruby or JRuby runtime version.
121
124
122
125
> [!IMPORTANT]
123
-
> Do NOT manually edit `gemfiles/*.gemfile` or `gemfiles/*.lock`. Instead, make changes to `appraisal/*.rb` and propagates your changes programmatically
126
+
> Do NOT manually edit `gemfiles/*.gemfile` or `gemfiles/*.lock`. Instead, make changes to `appraisal/*.rb` and propagate your changes programmatically.
124
127
125
-
To find out existing gemfiles in your environment, run
128
+
To find the existing gemfiles in your environment, run
126
129
127
130
```bash
128
131
bundle exec rake dependency:list
129
132
```
130
133
131
-
`dependency:list` is convenient to look for a specific gemfile path before assigning it to the environment variable `BUNDLE_GEMFILE`for doing all kinds of stuff.
134
+
`dependency:list` is convenient to look for a specific gemfile path before assigning it to the environment variable `BUNDLE_GEMFILE`. `BUNDLE_GEMFILE` is useful for doing all kinds of stuff, such as:
After introducing a new dependency group or changing existing one, run `bundle exec rake dependency:generate` to propagate the changes to the gemfile. `dependency:generate` is idempotent and only changes `gemfiles/*.gemfile` but not `gemfiles/*.lock`.
140
+
After introducing a new dependency group or changing an existing one, run `bundle exec rake dependency:generate` to propagate the changes to the gemfile. `dependency:generate` is idempotent and only changes `gemfiles/*.gemfile` but not `gemfiles/*.lock`.
138
141
139
-
To keep lockfile up-to-date with the gemfile, run `bundle exec rake dependency:lock`.
142
+
To keep lockfiles up-to-date with the gemfile, run `bundle exec rake dependency:lock`.
140
143
141
-
To install, run `bundle exec rake dependency:install`.
144
+
To install the dependencies, run `bundle exec rake dependency:install`.
142
145
143
146
Both `dependency:lock` and `dependency:install` can be provided with a specific gemfile path (from `dependency:list`) or pattern to target specific groups. For example:
144
147
145
148
```bash
146
-
#Generates lockfiles for all the stripe groups with `stripe_*` pattern
149
+
#Generate lockfiles for all the stripe groups with `stripe_*` pattern
> Add a new group only if the existing groups do not meet your requirements, or if adding a new dependency to an existing group is impractical.
@@ -171,18 +174,18 @@ For example, if you want tests to run only on Ruby 3.3 for tracing, you can defi
171
174
}
172
175
```
173
176
174
-
2. Define the required gems in the corresponding Appraisal file. For this example, we are going to use [`Appraisal/ruby-3.3.rb`](../Appraisal/ruby-3.3.rb). Let's define what `rails-edge` group needs.
177
+
2. Define the required gems in the corresponding Appraisal file. For this example, we are going to use [`Appraisal/ruby-3.3.rb`](../Appraisal/ruby-3.3.rb). Let's define what the `rails-edge` group needs.
175
178
176
179
```ruby
177
180
appraise 'rails-edge'do
178
181
gem 'rails', '>= 8'
179
182
end
180
183
```
181
184
182
-
3. Now let's generate that dependency Gemfile with `rake`, simply run
185
+
3. Now let's generate that dependency Gemfile with `rake`. Simply run
183
186
184
187
> [!IMPORTANT]
185
-
> Ensure you are using Ruby 3.3 as the current Ruby version (`ruby -v`) or run commands within a Docker container.
188
+
> Ensure you are either using Ruby 3.3 as the current Ruby version (`ruby -v`) or running commands within a Docker container.
186
189
187
190
```console
188
191
$ bundle exec rake dependency:generate
@@ -242,7 +245,7 @@ At this point, the new tests will be automatically included in the CI that runs
242
245
When running tests, you may pass additional args as parameters to the Rake task. For example:
A webpage will be generated at `coverage/report/index.html` with the resulting report.
262
265
263
266
Because you are likely not running all tests locally, your report will contain partial coverage results.
264
-
You *must* check the CI step `coverage` for the complete test coverage report, ensuring coverage is not
265
-
decreased.
267
+
You *must* check the CI step `coverage` for the complete test coverage report, ensuring coverage does not
268
+
decrease.
266
269
267
270
**Ensuring tests don't leak resources**
268
271
269
-
Tests execution can create resources that are hard to track: threads, sockets, files, etc. Because these resources can come
270
-
from the both the test setup as well as the code under test, making sure all resources are properly disposed is important
272
+
Test execution can create resources that are hard to track: threads, sockets, files, etc. Because these resources can come
273
+
from both the test setup as well as the test code itself, making sure all resources are properly disposed of is important
271
274
to prevent the application from inadvertently creating cumulative resources during its execution.
272
275
273
276
When running tests that utilize threads, you might see an error message similar to this one:
@@ -288,21 +291,23 @@ Thread Backtrace:
288
291
This means that this test did not finish all threads by the time the test had finished. In this case, the thread
289
292
creation can be traced to `workers_integration_spec.rb:245:in 'new'`. The thread itself is sleeping at `workers_integration_spec.rb:262:in 'sleep'`.
290
293
291
-
The actionable in this case would be to ensure that the thread created in `workers_integration_spec.rb:245` is properly terminated by invoking `Thread#join` during the test tear down, which will wait for the thread to finish before returning.
294
+
The actionable in this case would be to ensure that the thread created in `workers_integration_spec.rb:245` is properly terminated by invoking `Thread#join` during the test teardown, which will wait for the thread to finish before returning.
292
295
293
296
Depending on the situation, the thread in question might need to be forced to terminate. It's recommended to have a mechanism in place to terminate it (a shared variable that changes value when the thread should exit), but as a last resort, `Thread#terminate` forces the thread to finish. Keep in mind that regardless of the termination method, `Thread#join` must be called to ensure that the thread has completely finished its shutdown process.
294
297
295
298
**The APM Test Agent**
296
299
297
300
The APM test agent emulates the APM endpoints of the Datadog Agent. The Test Agent container
298
-
runs alongside the Ruby tracer locally and in CI, handles all traces during test runs and performs a number
301
+
runs alongside the Ruby tracer locally and in CI, handles all traces during test runs, and performs a number
299
302
of 'Trace Checks'. For more information on these checks, see:
0 commit comments