feat(unittest): add unittest support for test visibility (#6559)

## Motivation
This PR aims to add unittest support for `dd-tracer-py` which is a
built-in Python testing library widely used.

So far, this PR is for test visibility only. It is planned to add full
CI Visibility to unittest in the future.

## Changes
Added test visibility support for unittests behind a feature flag. The
`DD_CIVISIBILITY_UNITTEST_ENABLED` environment variable must be enabled
in order to use unittest test visibility.

## Example

You can find an example of the trace JSON in this
[span](https://dd.datad0g.com/ci/test-runs?query=test_level%3Atest%20%40test.service%3Aericnavarro-test%20&currentTab=overview&eventStack=AgAAAYoI6g9uHpHMiwAAAAAAAAAYAAAAAEFZb0k2aEVjQUFEaEhyTWEyU1AwZkRoYgAAACQAAAAAMDE4YTA5MWUtNjZiNy00MTM1LWJmM2YtYTgxY2U5YWRhZDgz&graphType=flamegraph&index=citest&sort=time&spanID=9606617518799500644&testId=AgAAAYoI6g9uHpHMiwAAAAAAAAAYAAAAAEFZb0k2aEVjQUFEaEhyTWEyU1AwZkRoYgAAACQAAAAAMDE4YTA5MWUtNjZiNy00MTM1LWJmM2YtYTgxY2U5YWRhZDgz&trace=AgAAAYoI6g9uHpHMiwAAAAAAAAAYAAAAAEFZb0k2aEVjQUFEaEhyTWEyU1AwZkRoYgAAACQAAAAAMDE4YTA5MWUtNjZiNy00MTM1LWJmM2YtYTgxY2U5YWRhZDgz&start=1690988854106&end=1691593654106&paused=false)

## Checklist

- [X] Change(s) are motivated and described in the PR description.
- [X] Testing strategy is described if automated tests are not included
in the PR.
- [X] Risk is outlined (performance impact, potential for breakage,
maintainability, etc).
- [X] Change is maintainable (easy to change, telemetry, documentation).
- [X] [Library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
are followed. If no release note is required, add label
`changelog/no-changelog`.
- [X] Documentation is included (in-code, generated user docs, [public
corp docs](https://github.com/DataDog/documentation/)).
- [X] Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist

- [x] Title is accurate.
- [x] No unnecessary changes are introduced.
- [x] Description motivates each change.
- [x] Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes unless absolutely necessary.
- [x] Testing strategy adequately addresses listed risk(s).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] Release note makes sense to a user of the library.
- [x] Reviewer has explicitly acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment.
- [x] Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)

---------

Co-authored-by: Emmett Butler <[email protected]>
Co-authored-by: Romain Komorn <[email protected]>
Co-authored-by: Munir Abdinur <[email protected]>

Author: 4 people

.circleci/config.templ.yml

@@ -784,6 +784,13 @@ jobs:
       - run_test:
           pattern: 'pytest'
 
+  unittest:
+    <<: *contrib_job
+    steps:
+      - run_test:
+          pattern: 'unittest'
+
+
   asynctest:
     executor: ddtrace_dev
     steps:

.riot/requirements/10b31b2.txt

@@ -0,0 +1,21 @@
+#
+# This file is autogenerated by pip-compile with Python 3.8
+# by the following command:
+#
+#    pip-compile --no-annotate .riot/requirements/10b31b2.in
+#
+attrs==23.1.0
+coverage[toml]==7.3.0
+exceptiongroup==1.1.3
+hypothesis==6.45.0
+iniconfig==2.0.0
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==23.1
+pluggy==1.3.0
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1
+sortedcontainers==2.4.0
+tomli==2.0.1

.riot/requirements/16b3d1d.txt

@@ -0,0 +1,26 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile --no-annotate .riot/requirements/16b3d1d.in
+#
+attrs==22.1.0
+coverage==5.5
+hypothesis==5.33.2
+importlib-metadata==2.1.3
+iniconfig==1.1.1
+mock==3.0.5
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==20.9
+pathlib2==2.3.7.post1
+pluggy==0.13.1
+py==1.11.0
+pyparsing==2.4.7
+pytest-cov==2.12.1
+pytest-mock==3.5.1
+pytest==6.1.2
+six==1.16.0
+sortedcontainers==2.4.0
+toml==0.10.2
+zipp==1.2.0

.riot/requirements/1b0a62d.txt

@@ -0,0 +1,19 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile --no-annotate .riot/requirements/1b0a62d.in
+#
+attrs==23.1.0
+coverage[toml]==7.3.0
+hypothesis==6.45.0
+iniconfig==2.0.0
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==23.1
+pluggy==1.3.0
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1
+sortedcontainers==2.4.0

.riot/requirements/1bd6f1c.txt

@@ -0,0 +1,36 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile --no-annotate .riot/requirements/1bd6f1c.in
+#
+atomicwrites==1.4.1
+attrs==21.4.0
+backports.functools-lru-cache==1.6.6
+configparser==4.0.2
+contextlib2==0.6.0.post1
+coverage==5.5
+enum34==1.1.10
+funcsigs==1.0.2
+futures==3.4.0
+hypothesis==4.57.1
+importlib-metadata==2.1.3
+mock==3.0.5
+more-itertools==5.0.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==20.9
+pathlib2==2.3.7.post1
+pluggy==0.13.1
+py==1.11.0
+pyparsing==2.4.7
+pytest-cov==2.12.1
+pytest-mock==2.0.0
+pytest==4.6.11
+scandir==1.10.0
+six==1.16.0
+sortedcontainers==2.4.0
+toml==0.10.2
+typing==3.10.0.0
+wcwidth==0.2.6
+zipp==1.2.0

.riot/requirements/1cf1760.txt

@@ -0,0 +1,24 @@
+#
+# This file is autogenerated by pip-compile with Python 3.7
+# by the following command:
+#
+#    pip-compile --config=pyproject.toml --no-annotate --resolver=backtracking .riot/requirements/1cf1760.in
+#
+attrs==23.1.0
+coverage[toml]==7.2.7
+exceptiongroup==1.1.3
+hypothesis==6.45.0
+importlib-metadata==6.7.0
+iniconfig==2.0.0
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==23.1
+pluggy==1.2.0
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1
+sortedcontainers==2.4.0
+tomli==2.0.1
+typing-extensions==4.7.1
+zipp==3.15.0

.riot/requirements/3013656.txt

@@ -0,0 +1,21 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --no-annotate .riot/requirements/3013656.in
+#
+attrs==23.1.0
+coverage[toml]==7.3.0
+exceptiongroup==1.1.3
+hypothesis==6.45.0
+iniconfig==2.0.0
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==23.1
+pluggy==1.3.0
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1
+sortedcontainers==2.4.0
+tomli==2.0.1

.riot/requirements/d6a02a4.txt

@@ -0,0 +1,25 @@
+#
+# This file is autogenerated by pip-compile with python 3.6
+# To update, run:
+#
+#    pip-compile --no-annotate .riot/requirements/d6a02a4.in
+#
+attrs==22.2.0
+coverage[toml]==6.2
+hypothesis==6.31.6
+importlib-metadata==4.8.3
+iniconfig==1.1.1
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==21.3
+pluggy==1.0.0
+py==1.11.0
+pyparsing==3.1.1
+pytest==7.0.1
+pytest-cov==4.0.0
+pytest-mock==3.6.1
+sortedcontainers==2.4.0
+tomli==1.2.3
+typing-extensions==4.1.1
+zipp==3.6.0

.riot/requirements/d75c291.txt

@@ -0,0 +1,21 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+#    pip-compile --no-annotate .riot/requirements/d75c291.in
+#
+attrs==23.1.0
+coverage[toml]==7.3.0
+exceptiongroup==1.1.3
+hypothesis==6.45.0
+iniconfig==2.0.0
+mock==5.1.0
+msgpack==1.0.5
+opentracing==2.4.0
+packaging==23.1
+pluggy==1.3.0
+pytest==7.4.0
+pytest-cov==4.1.0
+pytest-mock==3.11.1
+sortedcontainers==2.4.0
+tomli==2.0.1

ddtrace/_monkey.py

@@ -89,6 +89,7 @@
     "openai": True,
     "langchain": True,
     "subprocess": True,
+    "unittest": True,
 }
 
 

ddtrace/contrib/pytest/plugin.py

@@ -26,6 +26,7 @@
 from ddtrace.contrib.pytest.constants import HELP_MSG
 from ddtrace.contrib.pytest.constants import KIND
 from ddtrace.contrib.pytest.constants import XFAIL_REASON
+from ddtrace.contrib.unittest import unpatch as unpatch_unittest
 from ddtrace.ext import SpanTypes
 from ddtrace.ext import test
 from ddtrace.internal.ci_visibility import CIVisibility as _CIVisibility
@@ -214,7 +215,8 @@ def _start_test_module_span(pytest_package_item=None, pytest_module_item=None):
     test_module_span.set_tag_str(test.FRAMEWORK_VERSION, pytest.__version__)
     test_module_span.set_tag_str(test.COMMAND, _get_pytest_command(item.config))
     test_module_span.set_tag_str(_EVENT_TYPE, _MODULE_TYPE)
-    test_module_span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
+    if test_session_span:
+        test_module_span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
     test_module_span.set_tag_str(_MODULE_ID, str(test_module_span.span_id))
     test_module_span.set_tag_str(test.MODULE, _get_module_name(item, is_package))
     test_module_span.set_tag_str(test.MODULE_PATH, _get_module_path(item))
@@ -250,7 +252,8 @@ def _start_test_suite_span(item, test_module_span, should_enable_coverage=False)
     test_suite_span.set_tag_str(test.FRAMEWORK_VERSION, pytest.__version__)
     test_suite_span.set_tag_str(test.COMMAND, _get_pytest_command(item.config))
     test_suite_span.set_tag_str(_EVENT_TYPE, _SUITE_TYPE)
-    test_suite_span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
+    if test_session_span:
+        test_suite_span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
     test_suite_span.set_tag_str(_SUITE_ID, str(test_suite_span.span_id))
     test_module_path = None
     if test_module_span is not None:
@@ -300,6 +303,7 @@ def pytest_addoption(parser):
 
 
 def pytest_configure(config):
+    unpatch_unittest()
     config.addinivalue_line("markers", "dd_tags(**kwargs): add tags to current span")
     if is_enabled(config):
         _CIVisibility.enable(config=ddtrace.config.pytest)
@@ -481,7 +485,8 @@ def pytest_runtest_protocol(item, nextitem):
         span.set_tag_str(_EVENT_TYPE, SpanTypes.TEST)
         span.set_tag_str(test.NAME, item.name)
         span.set_tag_str(test.COMMAND, _get_pytest_command(item.config))
-        span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
+        if test_session_span:
+            span.set_tag_str(_SESSION_ID, str(test_session_span.span_id))
 
         span.set_tag_str(_MODULE_ID, str(test_module_span.span_id))
         span.set_tag_str(test.MODULE, test_module_span.get_tag(test.MODULE))

ddtrace/contrib/unittest/__init__.py

@@ -0,0 +1,34 @@
+"""
+The unittest integration traces test executions.
+
+
+Enabling
+~~~~~~~~
+
+The unittest integration is enabled automatically when using
+:ref:`ddtrace-run<ddtracerun>` or :func:`patch_all()<ddtrace.patch_all>`.
+
+Alternately, use :func:`patch()<ddtrace.patch>` to manually enable the integration::
+
+    from ddtrace import patch
+    patch(unittest=True)
+
+Global Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+.. py:data:: ddtrace.config.unittest["operation_name"]
+
+   The operation name reported by default for unittest traces.
+
+   This option can also be set with the ``DD_UNITTEST_OPERATION_NAME`` environment
+   variable.
+
+   Default: ``"unittest.test"``
+"""
+from .patch import patch
+from .patch import unpatch
+
+
+__all__ = ["patch", "unpatch"]
+
+patch()

ddtrace/contrib/unittest/constants.py

@@ -0,0 +1,5 @@
+COMPONENT_VALUE = "unittest"
+FRAMEWORK = "unittest"
+KIND = "test"
+
+TEST_OPERATION_NAME = "unittest.test"