Skip to content

Commit

Permalink
Update README section on writing tests
Browse files Browse the repository at this point in the history
* Add new section on how to add new dependency group
  • Loading branch information
Strech committed Jan 22, 2025
1 parent 97d8583 commit 838e8c4
Showing 1 changed file with 77 additions and 28 deletions.
105 changes: 77 additions & 28 deletions docs/DevelopmentGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,34 +44,6 @@ New tests should be written as RSpec tests in the `spec/datadog` folder. Test fi

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.

**Considerations for CI**

All tests should run in CI. When adding new `_spec.rb` files, you may need to add rake task to ensure your test file is run in CI.

- Ensure that there is a corresponding Rake task defined in `Rakefile` under the `spec` namespace, whose pattern matches your test file. For example

```ruby
namespace :spec do
RSpec::Core::RakeTask.new(:foo) do |t, args|
t.pattern = "spec/datadog/tracing/contrib/foo/**/*_spec.rb"
t.rspec_opts = args.to_a.join(' ')
end
end
```

- Ensure the Rake task is configured to run for the appropriate Ruby runtimes, by adding it to our `Matrixfile`. You should find the task with `bundle exec rake -T test:foo` after adding it.

```ruby
{
'foo' => {
# With default dependencies for each Ruby runtime
'' => '✅ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ 3.3 / ✅ 3.4 / ✅ jruby',
# or with dependency group definition `foo-on-rails`, that includes additional gems
'foo-on-rails' => '✅ 2.1 / ✅ 2.2 / ✅ 2.3 / ✅ 2.4 / ✅ 2.5 / ✅ 2.6 / ✅ 2.7 / ✅ 3.0 / ✅ 3.1 / ✅ 3.2 / ✅ 3.3 / ✅ 3.4 / ✅ jruby'
},
}
```

### Running tests

`bundle exec rake ci` will run the entire test suite with any given Ruby runtime, just as CI does. However, this is not recommended because it is going take a long time.
Expand Down Expand Up @@ -149,6 +121,83 @@ bundle exec rake dependency:lock['/app/gemfiles/ruby_3.3_stripe_*.gemfile']
bundle exec rake dependency:lock['/app/gemfiles/ruby_3.3_stripe_latest.gemfile']
```

**How to add new dependency group**

1. Pick the Ruby runtime and group name you want your tests to run. When defining a new group, try to match the format `scope:group`.
Let's say you want it to run only on Ruby 3.3 for profiling, than you can define it in the [`Matfixfile`](../Matrixfile).

```ruby
{
'tracing:ruby-on-rails' => {
# With default dependencies for each Ruby runtime
'' => '❌ 2.5 / ❌ 2.6 / ❌ 2.7 / ❌ 3.0 / ❌ 3.1 / ❌ 3.2 / ✅ 3.3 / ❌ 3.4 / ❌ jruby'
# or with dependency group definition `ruby-on-rails`, that includes additional gems or specific versions
'rails-1' => '❌ 2.5 / ❌ 2.6 / ❌ 2.7 / ❌ 3.0 / ❌ 3.1 / ❌ 3.2 / ✅ 3.3 / ❌ 3.4 / ❌ jruby'
'rails-edge' => '❌ 2.5 / ❌ 2.6 / ❌ 2.7 / ❌ 3.0 / ❌ 3.1 / ❌ 3.2 / ✅ 3.3 / ❌ 3.4 / ❌ jruby'
# ...
}
}
```

2. Define the required gems in corresponding Appraisal file, in our case it is [`Appraisal/ruby-3.3.rb`](../Appraisal/ruby-3.3.rb). Let's define what is `rails-edge` group means.

```ruby
appraise 'rails-42' do
gem 'rails', '>= 8'
end
```

3. Now let's generate that dependency Gemfile with `rake`, simply run

> [!IMPORTANT] Make sure, that you are running all commands with Ruby 3.3 as current ruby version `ruby -v` or in Docker container
```console
$ bundle exec rake dependency:generate
...
ruby-3.3_rails-edge
```

and you can verify that this dependency now is in the list

```console
$ bundle exec rake dependency:list
Ahoy! Here is a list of gemfiles you are looking for:

========================================
...
/Users/DataDog/dd-trace-rb/gemfiles/ruby_3.3_rails_edge.gemfile
```

4. Lock the gems versions with

```console
$ bundle exec rake dependency:lock[]
BUNDLE_GEMFILE=/Users/DataDog/dd-trace-rb/gemfiles/ruby_3.3_rails_edge.gemfile bundle lock --add-platform x86_64-linux aarch64-linux
Fetching gem metadata from https://rubygems.org/...........
Resolving dependencies...
Writing lockfile to /Users/DataDog/dd-trace-rb/gemfiles/ruby_3.3_rails_edge.gemfile.lock
```

5. The last step is to associate the newly generated group with some tests. It can be done in the [`Rakefile`](../Rakefile). It is important that the `scope:group` format of the new group match the rake task name. In our case, we should define it like this

```ruby
namespace :spec do
namespace :tracing do
RSpec::Core::RakeTask.new(:foo) do |t, args|
t.pattern = "spec/datadog/tracing/contrib/ruby-on-rails/**/*_spec.rb"
t.rspec_opts = args.to_a.join(' ')
end
end
end
```

and now you should be able to find it by running

```console
$ bundle exec rake -T test:tracing
rake test:tracing:ruby-on-rails[task_args] # Run spec:tracing:ruby-on-rails tests
```

**Passing arguments to tests**

When running tests, you may pass additional args as parameters to the Rake task. For example:
Expand Down

0 comments on commit 838e8c4

Please sign in to comment.