
[[debugging-test-problems]]
= Debugging Test Problems

There are a number of reasons that tests can fail to execute properly.
This chapter provides some approaches for dealing with these failures.


This chapter includes the following topics:

* <<debug-overview>>
* <<report-files>>
* <<debugging-details>>

[[debug-overview]]
== Overview

When a test fails, the first thing to do is to look at the test output which can be found in either the target/surefire-reports directory or the target/failsafe-reports directory. The test output provides a wealth of information about the test run, including the test results, the test output, and the stack trace of any exceptions that occurred during the test run. The CI server log may also provide information if the test fails during deployment or execution within the CI server.


[[report-files]]
== Report Files

You can generate test summary reports in HTML format by running the Maven surefire-reports plugin. See <<test-reports>> for the details on how to generate test reports. The resulting html summary allows you to browse which tests are failing and decide if more detail debugging is needed.

[[debugging-details]]
== Debugging Details

Jakarta EE TCK platform tests generally execute in two different JVMs. The first JVM is the client JVM, which is the JVM that runs the test client. The second JVM is the server JVM, which is the JVM that runs the test server. The client JVM is responsible for running the test client, which is the code that interacts with the test server. The server JVM is responsible for running the test server, which is the code that is being tested. The client JVM and the server JVM communicate with each other using the Arquillian protocol. The client JVM sends commands to the server JVM to start and stop the test server, and the server JVM sends test results back to the client JVM.

=== Debugging the Client JVM

To debug a test that is failing in the client JVM, use the `mvDebug` command rather than `mvn` to start the client JVM in debug mode. By default, the client JVM listens for debugger connections on port 5005. You can setup a remote debugger in your IDE to connect to the client JVM on port 5005. You would typically want to have the platform-tck repository loaded into your IDE so that you can set breakpoints in the test client code.

=== Debugging the Server JVM
If tests are failing in the server JVM, you need to start the server JVM in debug mode. To do this, you need to consult the documentation for the Arquillian connector you are using to start the server being tested. You would then setup a remote debugger in your IDE to connect to the server JVM on the port specified in the Arquillian configuration. You would also want to have the platform-tck repository loaded into your IDE so that you can set breakpoints in the server side components the test is calling.