jaegertracing / jaeger-lib

Testing

This library uses Go’s standard testing package for unit tests. Tests are run as part of the CI/CD pipeline using the GitHub Actions workflow.

The library relies on the testify testing framework for assertion helpers. This package is defined as a dependency in the Gopkg.toml file:

[[constraint]]
            name = "github.com/stretchr/testify"
            version = "1.4.0"

Unit Tests

Unit tests are organized within the *_test.go files alongside the code they test. The library uses several testing strategies:

  • Example-driven testing: The tests are often written in a way that demonstrates the expected usage of the code. For example:

    func TestSayHello(t *testing.T) {
              SayHello()
          }

    This test from the sample/sample_test.go file simply calls the SayHello() function and asserts that it doesn’t fail.

  • Property-based testing: This approach aims to test a wide range of inputs to ensure that the code behaves as expected. For example:

    func TestOptions(t *testing.T) {
              f1 := New()
              assert.NotNil(t, f1)
          }

    This test from the metrics/prometheus/factory_test.go file verifies that the New() function returns a non-nil object. This helps to ensure that the code is well-structured and can handle various situations.

  • Integration testing: These tests verify the interaction between different components of the library. An example:

    func TestTimerDefaultHelp(t *testing.T) {
              registry := prometheus.NewPedanticRegistry()
              f1 := New(WithRegisterer(registry))
              t1 := f1.Timer(metrics.TimerOptions{
                  Name: "rodriguez",
                  Tags: map[string]string{"x": "y"},
              })
              t1.Record(1 * time.Second)
          
              snapshot, err := registry.Gather()
              require.NoError(t, err)
          
              assert.EqualValues(t, "rodriguez", snapshot[0].GetHelp())
          }

    This test from the metrics/prometheus/factory_test.go file tests the interaction between the metrics package and the prometheus library. It creates a timer metric, records a value, and then verifies that the metric’s help text is set correctly.

Code Coverage

The library uses coveralls to track and report code coverage. The coveralls.io badge in the README.md file provides a visual representation of the coverage:

[cov-img]: https://coveralls.io/repos/jaegertracing/jaeger-lib/badge.svg?branch=main&service=github
          [cov]: https://coveralls.io/github/jaegertracing/jaeger-lib?branch=main

Testing with Gopkg.toml

The Gopkg.toml file defines the dependencies and the testing strategy. It defines go-tests and unused-packages for pruning.

[prune]
            go-tests = true
            unused-packages = true

This ensures that only the necessary dependencies are included in the project and that unused packages are removed.

Code Snippets

// metrics/metrics_test.go
          
          func TestNullMetrics(t *testing.T) {
              // This test is just for cover
              metrics.NullFactory.Timer(metrics.TimerOptions{
                  Name: "name",
              }).Record(0)
              metrics.NullFactory.Counter(metrics.Options{
                  Name: "name",
              }).Inc(0)
              metrics.NullFactory.Gauge(metrics.Options{
                  Name: "name",
              }).Update(0)
              metrics.NullFactory.Histogram(metrics.HistogramOptions{
                  Name: "name",
              }).Record(0)
              metrics.NullFactory.Namespace(metrics.NSOptions{
                  Name: "name",
              }).Gauge(metrics.Options{
                  Name: "name2",
              }).Update(0)
          }

This test from the metrics/metrics_test.go file uses the NullFactory to test the Timer, Counter, Gauge, and Histogram metrics.

Deployment

The library is packaged and deployed as a Go module. The README.md file provides information about the library’s import path:

The library's import path is `github.com/uber/jaeger-lib`.

The go.mod file specifies the library’s version and dependencies. The library is deployed to the Go module registry, which allows other projects to easily use it.

References

Additional Notes

  • The DCO file outlines the Developer Certificate of Origin, which clarifies the process for contributions.
  • The CONTRIBUTING.md file (not included in the context) provides guidance on how to contribute to the project.

Top-Level Directory Explanations

metrics/ - This directory contains the metrics implementation for the Jaeger Tracing library.

metrics/adapters/ - This subdirectory contains the various metric adapters for different backends.

metrics/expvar/ - This subdirectory contains the implementation for exposing metrics as HTTP endpoints using the expvar package.

metrics/fork/ - This subdirectory contains the implementation for forking metrics between processes.

metrics/go-kit/ - This subdirectory contains the Go-Kit integration for the Jaeger Tracing library.

metrics/go-kit/expvar/ - This subdirectory contains the expvar implementation for the Go-Kit integration.

metrics/go-kit/influx/ - This subdirectory contains the InfluxDB implementation for the Go-Kit integration.

metrics/metricstest/ - This subdirectory contains the testing implementation for the metrics.

metrics/multi/ - This subdirectory contains the implementation for collecting metrics from multiple sources.

metrics/prometheus/ - This subdirectory contains the Prometheus implementation for the Jaeger Tracing library.

metrics/tally/ - This subdirectory contains the implementation for counting metrics using the tally package.

sample/ - This directory contains a sample implementation for the Jaeger Tracing library.

utils/ - This directory contains various utility functions for the project.