datadog-ci 0.4.1 → 0.5.1

data/lib/datadog/ci.rb

@@ -10,16 +10,180 @@ module Datadog
   # @public_api
   module CI
     class << self
+      # Starts a {Datadog::CI::TestSession ci_test_session} that represents the whole test session run.
+      #
+      # Read Datadog documentation on test sessions
+      # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#sessions).
+      #
+      # Returns the existing test session if one is already active. There is at most a single test session per process.
+      #
+      # The {.start_test_session} method is used to mark the start of the test session:
+      # ```
+      # Datadog::CI.start_test_session(
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # Somewhere else after test run has ended
+      # Datadog::CI.active_test_session.finish
+      # ```
+      #
+      # Remember that calling {Datadog::CI::TestSession#finish} is mandatory.
+      #
+      # @param [String] service the service name for this session (optional, defaults to DD_SERVICE)
+      # @param [Hash<String,String>] tags extra tags which should be added to the test session.
+      # @return [Datadog::CI::TestSession] returns the active, running {Datadog::CI::TestSession}.
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
+      #         detected and test suite level visibility cannot be supported.
+      def start_test_session(service: nil, tags: {})
+        service ||= Datadog.configuration.service
+        recorder.start_test_session(service: service, tags: tags)
+      end
+
+      # The active, unfinished test session.
+      #
+      # Usage:
+      #
+      # ```
+      # # start a test session
+      # Datadog::CI.start_test_session(
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # somewhere else, access the session
+      # test_session = Datadog::CI.active_test_session
+      # test_session.finish
+      # ```
+      #
+      # @return [Datadog::CI::TestSession] the active test session
+      # @return [nil] if no test session is active
+      def active_test_session
+        recorder.active_test_session
+      end
+
+      # Starts a {Datadog::CI::TestModule ci_test_module} that represents a single test module (for most Ruby test frameworks
+      # module will correspond 1-1 to the test session).
+      #
+      # Read Datadog documentation on test modules
+      # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).
+      #
+      # Returns the existing test session if one is already active. There is at most a single test module per process
+      # active at any given time.
+      #
+      # The {.start_test_module} method is used to mark the start of the test session:
+      # ```
+      # Datadog::CI.start_test_module(
+      #   "my-module",
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # Somewhere else after the module has ended
+      # Datadog::CI.active_test_module.finish
+      # ```
+      #
+      # Remember that calling {Datadog::CI::TestModule#finish} is mandatory.
+      #
+      # @param [String] test_module_name the name for this module
+      # @param [String] service the service name for this session (optional, inherited from test session if not provided)
+      # @param [Hash<String,String>] tags extra tags which should be added to the test module (optional, some tags are inherited from test session).
+      # @return [Datadog::CI::TestModule] returns the active, running {Datadog::CI::TestModule}.
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
+      #         detected and test suite level visibility cannot be supported.
+      def start_test_module(test_module_name, service: nil, tags: {})
+        recorder.start_test_module(test_module_name, service: service, tags: tags)
+      end
+
+      # The active, unfinished test module.
+      #
+      # Usage:
+      #
+      # ```
+      # # start a test module
+      # Datadog::CI.start_test_module(
+      #   "my-module",
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # somewhere else, access the current module
+      # test_module = Datadog::CI.active_test_module
+      # test_module.finish
+      # ```
+      #
+      # @return [Datadog::CI::TestModule] the active test module
+      # @return [nil] if no test module is active
+      def active_test_module
+        recorder.active_test_module
+      end
+
+      # Starts a {Datadog::CI::TestSuite ci_test_suite} that represents a single test suite.
+      # If a test suite with given name is running, returns the existing test suite.
+      #
+      # Read Datadog documentation on test suites
+      # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).
+      #
+      # The {.start_test_suite} method is used to mark the start of a test suite:
+      # ```
+      # Datadog::CI.start_test_suite(
+      #   "calculator_tests",
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # Somewhere else after the suite has ended
+      # Datadog::CI.active_test_suite("calculator_tests").finish
+      # ```
+      #
+      # Remember that calling {Datadog::CI::TestSuite#finish} is mandatory.
+      #
+      # @param [String] test_suite_name the name of the test suite
+      # @param [String] service the service name for this test suite (optional, inherited from test session if not provided)
+      # @param [Hash<String,String>] tags extra tags which should be added to the test module (optional, some tags are inherited from test session)
+      # @return [Datadog::CI::TestSuite] returns the active, running {Datadog::CI::TestSuite}.
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
+      #         detected and test suite level visibility cannot be supported.
+      def start_test_suite(test_suite_name, service: nil, tags: {})
+        recorder.start_test_suite(test_suite_name, service: service, tags: tags)
+      end
+
+      # The active, unfinished test suite.
+      #
+      # Usage:
+      #
+      # ```
+      # # start a test suite
+      # Datadog::CI.start_test_suite(
+      #   "calculator_tests",
+      #   service: "my-web-site-tests",
+      #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
+      # )
+      #
+      # # Somewhere else after the suite has ended
+      # test_suite = Datadog::CI.active_test_suite("calculator_tests")
+      # test_suite.finish
+      # ```
+      #
+      # @return [Datadog::CI::TestSuite] the active test suite
+      # @return [nil] if no test suite with given name is active
+      def active_test_suite(test_suite_name)
+        recorder.active_test_suite(test_suite_name)
+      end
+
       # Return a {Datadog::CI::Test ci_test} that will trace a test called `test_name`.
       # Raises an error if a test is already active.
+      # If there is an active test session, the new test will be connected to the session.
+      # The test will inherit service name and tags from the running test session if not provided
+      # in parameters.
       #
       # You could trace your test using a <tt>do-block</tt> like:
       #
       # ```
       # Datadog::CI.trace_test(
       #   "test_add_two_numbers",
-      #   service_name: "my-web-site-tests",
-      #   operation_name: "test",
+      #   "calculator_tests",
+      #   service: "my-web-site-tests",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # ) do |ci_test|
       #   result = run_test
@@ -32,60 +196,59 @@ module Datadog
       # end
       # ```
       #
-      # The {#trace_test} method can also be used without a block in this way:
+      # The {.trace_test} method can also be used without a block in this way:
       # ```
       # ci_test = Datadog::CI.trace_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
-      #   operation_name: "test",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
-      # run_test
+      # # ... run test here ...
       # ci_test.finish
       # ```
       #
       # Remember that in this case, calling {Datadog::CI::Test#finish} is mandatory.
       #
       # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
-      # @param [String] operation_name defines label for a test span in trace view ("test" if it's missing)
-      # @param [String] service_name the service name for this test
+      # @param [String] test_suite_name name of test suite this test belongs to (example: "CalculatorTest").
+      # @param [String] service the service name for this test (optional, inherited from test session if not provided)
       # @param [Hash<String,String>] tags extra tags which should be added to the test.
       # @return [Object] If a block is provided, returns the result of the block execution.
       # @return [Datadog::CI::Test] If no block is provided, returns the active,
       #         unfinished {Datadog::CI::Test}.
-      # @yield Optional block where new newly created {Datadog::CI::Test} captures the execution.
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
+      # @yield Optional block where newly created {Datadog::CI::Test} captures the execution.
       # @yieldparam [Datadog::CI::Test] ci_test the newly created and active [Datadog::CI::Test]
-      #
-      # @public_api
-      def trace_test(test_name, service_name: nil, operation_name: "test", tags: {}, &block)
-        recorder.trace_test(test_name, service_name: service_name, operation_name: operation_name, tags: tags, &block)
+      # @yieldparam [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
+      def trace_test(test_name, test_suite_name, service: nil, tags: {}, &block)
+        recorder.trace_test(test_name, test_suite_name, service: service, tags: tags, &block)
       end
 
-      # Same as {#trace_test} but it does not accept a block.
+      # Same as {.trace_test} but it does not accept a block.
       # Raises an error if a test is already active.
       #
       # Usage:
       #
       # ```
       # ci_test = Datadog::CI.start_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
-      #   operation_name: "test",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
-      # run_test
+      # # ... run test here ...
       # ci_test.finish
       # ```
       #
       # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
-      # @param [String] operation_name the resource this span refers, or `test` if it's missing
-      # @param [String] service_name the service name for this span.
+      # @param [String] test_suite_name name of test suite this test belongs to (example: "CalculatorTest").
+      # @param [String] service the service name for this span (optional, inherited from test session if not provided)
       # @param [Hash<String,String>] tags extra tags which should be added to the test.
       # @return [Datadog::CI::Test] Returns the active, unfinished {Datadog::CI::Test}.
-      #
-      # @public_api
-      def start_test(test_name, service_name: nil, operation_name: "test", tags: {})
-        recorder.trace_test(test_name, service_name: service_name, operation_name: operation_name, tags: tags)
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
+      def start_test(test_name, test_suite_name, service: nil, tags: {})
+        recorder.trace_test(test_name, test_suite_name, service: service, tags: tags)
       end
 
       # Trace any custom span inside a test. For example, you could trace:
@@ -93,7 +256,7 @@ module Datadog
       # - database query
       # - any custom operation you want to see in your trace view
       #
-      # You can use thi method with a <tt>do-block</tt> like:
+      # You can use this method with a <tt>do-block</tt> like:
       #
       # ```
       # Datadog::CI.trace(
@@ -105,14 +268,14 @@ module Datadog
       # end
       # ```
       #
-      # The {#trace} method can also be used without a block in this way:
+      # The {.trace} method can also be used without a block in this way:
       # ```
       # ci_span = Datadog::CI.trace(
       #   "step",
       #   "Given I have 42 cucumbers",
       #   tags: {}
       # )
-      # run_test
+      # # ... run test here ...
       # ci_span.finish
       # ```
       # Remember that in this case, calling {Datadog::CI::Span#finish} is mandatory.
@@ -123,10 +286,10 @@ module Datadog
       # @return [Object] If a block is provided, returns the result of the block execution.
       # @return [Datadog::CI::Span] If no block is provided, returns the active,
       #         unfinished {Datadog::CI::Span}.
-      # @yield Optional block where new newly created {Datadog::CI::Span} captures the execution.
+      # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
+      # @yield Optional block where newly created {Datadog::CI::Span} captures the execution.
       # @yieldparam [Datadog::CI::Span] ci_span the newly created and active [Datadog::CI::Span]
-      #
-      # @public_api
+      # @yieldparam [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
       def trace(span_type, span_name, tags: {}, &block)
         recorder.trace(span_type, span_name, tags: tags, &block)
       end
@@ -166,9 +329,9 @@ module Datadog
       # ```
       # # start a test
       # Datadog::CI.start_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
-      #   operation_name: "test",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
       #
@@ -184,11 +347,30 @@ module Datadog
         recorder.active_test
       end
 
-      # Internal only, to finish a test use Datadog::CI::Test#finish
+      # Internal only, to finish a test use {Datadog::CI::Test#finish}
+      # @private
       def deactivate_test(test)
         recorder.deactivate_test(test)
       end
 
+      # Internal only, to finish a test session use {Datadog::CI::TestSession#finish}
+      # @private
+      def deactivate_test_session
+        recorder.deactivate_test_session
+      end
+
+      # Internal only, to finish a test module use {Datadog::CI::TestModule#finish}
+      # @private
+      def deactivate_test_module
+        recorder.deactivate_test_module
+      end
+
+      # Internal only, to finish a test suite use {Datadog::CI::TestSuite#finish}
+      # @private
+      def deactivate_test_suite(test_suite_name)
+        recorder.deactivate_test_suite(test_suite_name)
+      end
+
       private
 
       def components
@@ -207,6 +389,6 @@ require_relative "ci/contrib/cucumber/integration"
 require_relative "ci/contrib/rspec/integration"
 require_relative "ci/contrib/minitest/integration"
 
-# Extensions
-require_relative "ci/extensions"
-Datadog::CI::Extensions.activate!
+# Configuration extensions
+require_relative "ci/configuration/extensions"
+Datadog::CI::Configuration::Extensions.activate!

data/sig/datadog/ci/concurrent_span.rbs

@@ -0,0 +1,23 @@
+module Datadog
+  module CI
+    class ConcurrentSpan < Span
+      @mutex: Thread::Mutex
+
+      def initialize: (Datadog::Tracing::SpanOperation tracer_span) -> void
+      def passed!: () -> void
+      def failed!: (?exception: untyped?) -> void
+      def skipped!: (?exception: untyped?, ?reason: String?) -> void
+      def get_tag: (String key) -> untyped?
+      def set_tag: (String key, untyped? value) -> void
+      def set_metric: (String key, untyped value) -> void
+      def finish: () -> void
+      def set_tags: (Hash[untyped, untyped] tags) -> void
+
+      def set_environment_runtime_tags: () -> void
+
+      def set_default_tags: () -> void
+
+      def synchronize: () { () -> untyped } -> untyped
+    end
+  end
+end

data/sig/datadog/ci/configuration/components.rbs

@@ -2,9 +2,9 @@ module Datadog
   module CI
     module Configuration
       module Components : Datadog::Core::Configuration::Components
-        @ci_recorder: Datadog::CI::Recorder
+        @ci_recorder: Datadog::CI::TestVisibility::Recorder
 
-        attr_reader ci_recorder: Datadog::CI::Recorder
+        attr_reader ci_recorder: Datadog::CI::TestVisibility::Recorder
 
         def initialize: (untyped settings) -> void
 
@@ -13,6 +13,8 @@ module Datadog
         def build_agentless_transport: (untyped settings) -> Datadog::CI::TestVisibility::Transport?
         def build_evp_proxy_transport: (untyped settings, untyped agent_settings) -> Datadog::CI::TestVisibility::Transport
         def can_use_evp_proxy?: (untyped settings, untyped agent_settings) -> bool
+        def serializers_factory: (untyped settings) -> (singleton(Datadog::CI::TestVisibility::Serializers::Factories::TestSuiteLevel) | singleton(Datadog::CI::TestVisibility::Serializers::Factories::TestLevel))
+        def check_dd_site: (untyped settings) -> void
       end
     end
   end

data/sig/datadog/ci/configuration/extensions.rbs

@@ -0,0 +1,9 @@
+module Datadog
+  module CI
+    module Configuration
+      module Extensions
+        def self.activate!: () -> untyped
+      end
+    end
+  end
+end

data/sig/datadog/ci/ext/app_types.rbs

@@ -2,7 +2,12 @@ module Datadog
   module CI
     module Ext
       module AppTypes
-        TYPE_TEST: String
+        TYPE_TEST: "test"
+        TYPE_TEST_SESSION: "test_session_end"
+        TYPE_TEST_MODULE: "test_module_end"
+        TYPE_TEST_SUITE: "test_suite_end"
+
+        CI_SPAN_TYPES: Array[String]
       end
     end
   end

data/sig/datadog/ci/ext/settings.rbs

@@ -5,6 +5,9 @@ module Datadog
         ENV_MODE_ENABLED: String
         ENV_AGENTLESS_MODE_ENABLED: String
         ENV_AGENTLESS_URL: String
+        ENV_EXPERIMENTAL_TEST_SUITE_LEVEL_VISIBILITY_ENABLED: String
+
+        DD_SITE_ALLOWLIST: Array[String]
       end
     end
   end

data/sig/datadog/ci/ext/test.rbs

@@ -18,9 +18,24 @@ module Datadog
 
         TAG_SUITE: String
 
+        TAG_MODULE: String
+
         TAG_TRAITS: String
 
         TAG_TYPE: String
+
+        TAG_COMMAND: String
+
+        TAG_TEST_SESSION_ID: String
+
+        TAG_TEST_MODULE_ID: String
+
+        TAG_TEST_SUITE_ID: String
+
+        SPECIAL_TAGS: Array[String]
+
+        INHERITABLE_TAGS: Array[String]
+
         TAG_OS_ARCHITECTURE: String
 
         TAG_OS_PLATFORM: String

data/sig/datadog/ci/null_span.rbs

@@ -0,0 +1,37 @@
+module Datadog
+  module CI
+    class NullSpan < Span
+      def initialize: () -> void
+
+      def id: () -> nil
+
+      def name: () -> nil
+
+      def service: () -> nil
+
+      def span_type: () -> nil
+
+      def passed!: () -> nil
+
+      def failed!: (?exception: untyped?) -> nil
+
+      def skipped!: (?exception: untyped?, ?reason: untyped?) -> nil
+
+      def get_tag: (untyped key) -> nil
+
+      def set_tag: (untyped key, untyped value) -> nil
+
+      def set_metric: (untyped key, untyped value) -> nil
+
+      def finish: () -> nil
+
+      def set_tags: (untyped tags) -> nil
+
+      def set_environment_runtime_tags: () -> nil
+
+      def set_default_tags: () -> nil
+
+      def to_s: () -> untyped
+    end
+  end
+end

data/sig/datadog/ci/span.rbs

@@ -7,8 +7,12 @@ module Datadog
 
       def initialize: (Datadog::Tracing::SpanOperation tracer_span) -> void
 
+      def id: () -> Integer
+
       def name: () -> String
 
+      def service: () -> String
+
       def passed!: () -> void
 
       def failed!: (?exception: untyped?) -> void

data/sig/datadog/ci/test_module.rbs

@@ -0,0 +1,6 @@
+module Datadog
+  module CI
+    class TestModule < ConcurrentSpan
+    end
+  end
+end

data/sig/datadog/ci/test_session.rbs

@@ -0,0 +1,9 @@
+module Datadog
+  module CI
+    class TestSession < ConcurrentSpan
+      @inheritable_tags: Hash[untyped, untyped]
+
+      def inheritable_tags: () -> Hash[untyped, untyped]
+    end
+  end
+end

data/sig/datadog/ci/test_suite.rbs

@@ -0,0 +1,6 @@
+module Datadog
+  module CI
+    class TestSuite < ConcurrentSpan
+    end
+  end
+end

data/sig/datadog/ci/test_visibility/context/global.rbs

@@ -0,0 +1,39 @@
+module Datadog
+  module CI
+    module TestVisibility
+      module Context
+        class Global
+          @mutex: Thread::Mutex
+
+          @test_session: Datadog::CI::TestSession?
+          @test_module: Datadog::CI::TestModule?
+          @test_suites: Hash[String, Datadog::CI::TestSuite]
+
+          def initialize: () -> void
+
+          def fetch_or_activate_test_suite: (String test_suite_name) {() -> Datadog::CI::TestSuite} -> Datadog::CI::TestSuite
+
+          def fetch_or_activate_test_module: () {() -> Datadog::CI::TestModule} -> Datadog::CI::TestModule
+
+          def fetch_or_activate_test_session: () {() -> Datadog::CI::TestSession} -> Datadog::CI::TestSession
+
+          def active_test_session: () -> Datadog::CI::TestSession?
+
+          def active_test_suite: (String test_suite_name) -> Datadog::CI::TestSuite?
+
+          def service: () -> String?
+
+          def inheritable_session_tags: () -> Hash[untyped, untyped]
+
+          def active_test_module: () -> Datadog::CI::TestModule?
+
+          def deactivate_test_session!: () -> void
+
+          def deactivate_test_module!: () -> void
+
+          def deactivate_test_suite!: (String test_suite_name) -> void
+        end
+      end
+    end
+  end
+end

data/sig/datadog/ci/test_visibility/context/local.rbs

@@ -0,0 +1,23 @@
+module Datadog
+  module CI
+    module TestVisibility
+      module Context
+        class Local
+          @key: Symbol
+
+          def initialize: () -> void
+
+          def activate_test!: (Datadog::CI::Test test) ?{ () -> untyped } -> void
+
+          def deactivate_test!: (Datadog::CI::Test test) -> void
+
+          def active_test: () -> Datadog::CI::Test?
+
+          private
+
+          def active_test=: (Datadog::CI::Test? test) -> untyped
+        end
+      end
+    end
+  end
+end