Lab 1.2: Run Unit and Integration Tests

Background

Apache Tez has a well-structured test suite that spans unit tests, module-level integration tests, and full cluster integration tests using MiniTezCluster. Understanding how to run specific tests, read failures, and scope test execution is essential for contributor work — your patch must include a passing test run before upload.

Why This Lab Matters for Contributors

• You must run tests before submitting any patch
• Being able to run a single test class in seconds makes iteration fast
• Understanding test failure output is the first step to debugging
• Many flaky tests are contributor opportunities once you understand how tests work

How Tez Tests Are Organized

Tez tests fall into three categories:

For Level 1–3 work, focus exclusively on unit tests.

Key unit test classes in tez-dag (path: tez-dag/src/test/java/org/apache/tez/dag/app/dag/impl/):

Supporting test infrastructure in tez-dag/src/test/java/org/apache/tez/dag/app/:

Step-by-Step Tasks

Step 1: Run All Unit Tests in tez-dag

cd /path/to/tez
mvn test -pl tez-dag -am -q 2>&1 | tail -30

Expected duration: 3–8 minutes depending on hardware.

Expected completion:

[INFO] Tests run: NNNN, Failures: 0, Errors: 0, Skipped: NN
[INFO] BUILD SUCCESS

Some tests are marked @Ignore or skipped due to environment constraints — a non-zero Skipped count is normal.

Step 2: Run a Single Test Class

mvn test -pl tez-dag -am -Dtest=TestDAGImpl -q

Expected output (last few lines):

[INFO] Tests run: 42, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: X.XXX s
[INFO] BUILD SUCCESS

If a test fails, you will see:

[ERROR] Tests run: 42, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: X.XXX s
[ERROR] testDAGCreation(org.apache.tez.dag.app.dag.impl.TestDAGImpl): expected:<...> but was:<...>

Step 3: Run a Single Test Method

mvn test -pl tez-dag -am -Dtest=TestDAGImpl#testDAGCreation -q

This is the command you will use most often: run exactly one test after a code change to verify your fix.

Step 4: Read the Surefire Report

Maven writes detailed test results to:

tez-dag/target/surefire-reports/

For a failing test, read the .txt file for the test class:

cat tez-dag/target/surefire-reports/org.apache.tez.dag.app.dag.impl.TestDAGImpl.txt

This contains the full stack trace, which is often more informative than the Maven console output.

Step 5: Run Tests in tez-api

mvn test -pl tez-api -q

tez-api tests are faster and simpler. Key test classes:

Step 6: Run Tests in tez-runtime-library

mvn test -pl tez-runtime-library -am -q

This includes shuffle and I/O tests. Expected duration: 5–10 minutes.

Key test classes:

Step 7: Understand a Test Failure

Intentionally break a test to understand failure output:

1. Open tez-dag/src/main/java/org/apache/tez/dag/app/dag/impl/DAGImpl.java
2. Find the getTotalVertices() method
3. Add return 0; as the first line
4. Run mvn test -pl tez-dag -am -Dtest=TestDAGImpl -q
5. Read the failure output in both the console and the surefire report
6. Revert the change with git checkout tez-dag/src/main/java/org/apache/tez/dag/app/dag/impl/DAGImpl.java

This exercise makes test failure output familiar before you encounter a real failure.

Debugging Test Failures

Adding Log Output

Tez uses SLF4J + Log4j. To enable debug-level logging during a test run:

mvn test -pl tez-dag -am -Dtest=TestDAGImpl \
  -Dlog4j.configuration=file:src/test/resources/log4j.properties \
  -Dlog4j.logger.org.apache.tez=DEBUG

Running Tests with Remote Debug (IntelliJ)

To attach a debugger to a Maven test run:

mvn test -pl tez-dag -am -Dtest=TestDAGImpl \
  -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005"

In IntelliJ: Run → Attach to Process → port 5005. The test JVM pauses until IntelliJ connects.

Testing Checklist

Before submitting any patch:

• Run mvn test -pl <changed-module> -am — zero failures
• If adding a new test: mvn test -pl <module> -am -Dtest=<YourNewTest> passes
• Run mvn checkstyle:check -pl <changed-module> — zero violations
• If the change touches shuffle or I/O: run mvn test -pl tez-runtime-library -am

Expected Output

A clean test run for TestDAGImpl:

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.apache.tez.dag.app.dag.impl.TestDAGImpl
[INFO] Tests run: 42, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 12.345 s
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 42, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] BUILD SUCCESS

Stretch Goals

1. Find all test classes in tez-dag that test the VertexImpl state machine:

   find tez-dag/src/test -name "*.java" | xargs grep -l "VertexImpl"
   

2. Count the total number of test methods in TestVertexImpl:

   grep -c "@Test" tez-dag/src/test/java/org/apache/tez/dag/app/dag/impl/TestVertexImpl.java
   

3. Identify which test classes take the longest to run by examining surefire report timestamps:

   grep "Time elapsed" tez-dag/target/surefire-reports/*.txt | sort -t= -k2 -rn | head -10
   

4. Find tests that use MockDAGAppMaster to understand the test infrastructure pattern:

   grep -rl "MockDAGAppMaster" tez-dag/src/test/
   

Related Real-World Issue Types

• Flaky tests (timing-dependent, environment-dependent) — a major contributor opportunity
• Tests that don't assert anything meaningful — test quality improvements
• Missing test coverage for error paths — discoverable by reading state machine code