Update docs for running tests (#12987)

Co-authored-by: Steve Rao <raozihao.rzh@alibaba-inc.com>

CONTRIBUTING.md

@@ -87,7 +87,8 @@ https://gradle.com/s/ila4qwp5lcf5s
 ```
 
 Opening the build scan link can sometimes take several seconds (it's a large build), but it
-typically makes it a lot clearer what's failing.
+typically makes it a lot clearer what's failing. Sometimes there will be several build scans in a
+log, so look for one that follows the "BUILD FAILED" message.
 
 You can also try the "Explain error" button at the top of the GitHub Actions page,
 which often does a reasonable job of parsing the long build log and displaying the important part.

docs/contributing/debugging.md

@@ -3,6 +3,17 @@
 Debugging javaagent instrumentation can be a challenging task since instrumentation
 code is directly inlined into target classes.
 
+## Indy compatible instrumentation
+
+For instrumentation that has been migrated to use the
+[invokedynamic based instrumentation mechanism](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/8999),
+you can leverage breakpoints and standard debugging strategies by adding `-PtestIndy=true` to the
+gradle command when running tests:
+
+```
+./gradlew -PtestIndy=true :instrumentation:<INSTRUMENTATION_NAME>:test
+```
+
 ## Advice methods
 
 Breakpoints do not work in advice methods, because their code is directly inlined

docs/contributing/running-tests.md

@@ -4,14 +4,14 @@
 
 Open Telemetry Auto Instrumentation's minimal supported version is java 8.
 All jar files that we produce, unless noted otherwise, have bytecode
-compatible with java 8 runtime. Our test suite is executed against
+compatibility with the java 8 runtime. Our test suite is executed against
 java 8, all LTS versions and the latest non-LTS version.
 
 Some libraries that we auto-instrument may have higher minimal requirements.
-In this case we compile and test corresponding auto-instrumentation with
-higher java version as required by library. The resulting classes will have
-higher bytecode level, but as it matches library's java version, no runtime
-problem arise.
+In these cases, we compile and test the corresponding auto-instrumentation with
+higher java versions as required by the libraries. The resulting classes will
+have a higher bytecode level, but since it will match the library's java version,
+no runtime problems arise.
 
 ## Instrumentation tests
 
@@ -22,10 +22,11 @@ instrumented library.
 
 ### Executing tests with specific java version
 
-We run all tests on Java 11 by default, along with Java 8 and 15. To run on the later, set the
-`testJavaVersion` Gradle property to the desired major version, e.g., `./gradlew test -PtestJavaVersion=8`,
-`./gradlew test -PtestJavaVersion=15`. If you don't have a JDK of these versions
-installed, Gradle will automatically download it for you.
+We run all tests on `Java 21` by default, along with Java 8, 11, 17, and 23. To run on
+a specific version, set the `testJavaVersion` gradle property to the desired major
+version, e.g., `./gradlew test -PtestJavaVersion=8`, `./gradlew test -PtestJavaVersion=23`.
+If you don't have a JDK of these versions installed, Gradle will automatically download
+it for you.
 
 ### Executing tests against the latest versions of libraries under instrumentation
 
@@ -36,7 +37,7 @@ To run these tests locally, add `-PtestLatestDeps=true` to your existing `gradle
 
 ### Executing single test
 
-Executing `./gradlew :instrumentation:<INSTRUMENTATION_NAME>:test --tests <GROOVY TEST FILE NAME>` will run only the selected test.
+Executing `./gradlew :instrumentation:<INSTRUMENTATION_NAME>:test --tests <TEST FILE NAME>` will run only the selected test.
 
 ### How to prevent linting and formatting warnings from failing tests
 
@@ -52,7 +53,7 @@ The `dev` flag will ignore warnings in tests.
 
 ## Smoke tests
 
-The smoke tests are not run as part of a global `test` task run since they take a long time and are
+The smoke tests are not run as part of a global `test` task since they take a long time and are
 not relevant for most contributions. Explicitly specify `:smoke-tests:test` to run them.
 
 If you need to run a specific smoke test suite:
@@ -73,11 +74,10 @@ If you want to run a specific smoke test:
 ./gradlew :smoke-tests:test --tests '*SpringBootSmokeTest*'
 ```
 
-## Smoke OpenTelemetry starter tests
+## OpenTelemetry starter smoke tests
 
-Smoke tests for the [OpenTelemetry Spring starter](../../instrumentation/spring/starters/spring-boot-starter/README.md).
-
-You can execute the tests in a JVM (`./gradlew smoke-tests-otel-starter:test`) or as Spring native tests (`./gradlew smoke-tests-otel-starter:nativeTest`).
+Smoke tests for the [OpenTelemetry Spring starter](../../instrumentation/spring/starters/spring-boot-starter/README.md)
+can be executed in a JVM (`./gradlew smoke-tests-otel-starter:test`) or as Spring Native tests (`./gradlew smoke-tests-otel-starter:nativeTest`).
 
 ## GraalVM native test
 
@@ -100,22 +100,13 @@ old containers, images and volumes using `docker system prune --volumes`.
 For some container environments, such as rootless Podman or a remotely hosted Docker,
 testcontainers may need additional configuration to successfully run the tests.
 The following environment variables can be used for configuration:
- - `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` - The location of the Docker socket on the host. Default is `/var/run/docker.sock`
- - `TESTCONTAINERS_HOST_OVERRIDE` - The hostname used for container-to-container communication. Default Docker is `localhost`, but rootless Podman uses `host.containers.internal`
+- `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` - The location of the Docker socket on the host. Default is `/var/run/docker.sock`
+- `TESTCONTAINERS_HOST_OVERRIDE` - The hostname used for container-to-container communication. Default Docker is `localhost`, but rootless Podman uses `host.containers.internal`
 
 # Troubleshooting CI Test Failures
 
-CI test logs are pretty big around 75MB. To make it easier to troubleshoot test failures, you can download the raw logs from the CI job and then look for
-`Publishing build scan...` in the logs. Copy the URL from the logs and open it in a browser. This will give you a nice view of the test execution breakdown.
-
-## How to download the raw logs
+See [Troubleshooting CI Test Failures](../../CONTRIBUTING.md#troubleshooting-pr-build-failures) for common issues and solutions.
 
-1. Click on the `Details` link in one of the failing CI jobs under `Some checks were not successful` section of your PR.
-2. Click on one of the failed tests in the left panel.
-3. Click on the `Setting` gear in the top right corner of the logs panel.
-4. Right click on 'View raw logs' and then 'Save link as' to save the page as a text file locally.
-5. Once the file is downloaded, open it in a text editor and search for `Publishing build scan...` to find the URL.
-6. Open the URL in a browser to view the test execution breakdown. It might prompt you to "Activate your Build Scan" the very 1st time, you can use your own email address and activate it via email.
+# Debugging
 
-Unfortunately, the Build Scan service hosted via Develocity has an allowed size limits of the free build scans. Once you exceed the limit, then you won't be able to view the scan anymore.
-Then you can just use the raw logs to search for "FAILED" or "Task failed with an exception" to identify the failing tests.
+For information on debugging tests or instrumentation, see [Debugging](debugging.md).