-q, -X, -DskipTests, -Dtest and -B

A Maven command has two parts: what to run (a phase or a goal) and how to run it. The second part is a handful of switches that every project uses and every log of this course already contains: -B in all of them, and -Dtest, -DskipTests, -q and -X when the situation asks for them. This article runs each one on the calculator and shows what changed.

The project

The project of the package article, jar plugin included: three tests, a main class and a manifest that names it.

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>calc</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> <junit.version>5.14.3</junit.version> </properties> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>${junit.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>3.5.0</version> <configuration> <archive> <manifest> <mainClass>com.example.calc.Calc</mainClass> </manifest> </archive> </configuration> </plugin> </plugins> </build> </project>

src/main/java/com/example/calc/Calc.java

package com.example.calc; public class Calc { public static int add(int a, int b) { return a + b; } public static int divide(int a, int b) { if (b == 0) { throw new IllegalArgumentException("division by zero"); } return a / b; } public static void main(String[] args) { System.out.println("1 + 2 = " + add(1, 2)); } }

src/test/java/com/example/calc/CalcTest.java

package com.example.calc; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertThrows; import org.junit.jupiter.api.Test; class CalcTest { @Test void addsTwoNumbers() { assertEquals(4, Calc.add(1, 3)); } @Test void dividesTwoNumbers() { assertEquals(3, Calc.divide(9, 3)); } @Test void rejectsDivisionByZero() { IllegalArgumentException e = assertThrows(IllegalArgumentException.class, () -> Calc.divide(1, 0)); assertEquals("division by zero", e.getMessage()); } }

-q

-q is quiet: the [INFO] lines go away and only warnings and errors stay. A successful build then prints nothing at all, and the shell status is the only thing left to read:

mvn -B -q compile; echo "status: $?"

status: 0

That is what a script wants: no output on success, the error lines on failure. It is also how help:evaluate -DforceStdout prints one value and nothing else, and the pages of this course use the pair for exactly that reason.

-X

-X is the other end: the debug log, which starts with the version of Maven and of the JDK, prints the configuration of every goal before it runs and ends with the dependency graph Maven resolved. The log of mvn -B -X package is 400 lines for this project; the excerpt below is the plan it prints, which the lifecycle article reads in full.

mvn -B -X package > debug.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" debug.log

status: 0
Apache Maven 3.9.16 (2bdd9fddda4b155ebf8000e807eb73fd829a51d5)
Maven home: /usr/share/java/maven-3
Java version: 21.0.13.1, vendor: Alpine, runtime: /usr/lib/jvm/java-21-openjdk
Default locale: en_US, platform encoding: UTF-8
OS name: <OS>
[DEBUG] Created new class realm maven.api
[DEBUG] Goal: org.apache.maven.plugins:maven-resources-plugin:3.4.0:resources (default-resources)
[DEBUG] Goal: org.apache.maven.plugins:maven-compiler-plugin:3.15.0:compile (default-compile)
[DEBUG] Goal: org.apache.maven.plugins:maven-resources-plugin:3.4.0:testResources (default-testResources)
[DEBUG] Goal: org.apache.maven.plugins:maven-compiler-plugin:3.15.0:testCompile (default-testCompile)
[DEBUG] Goal: org.apache.maven.plugins:maven-surefire-plugin:3.5.4:test (default-test)
[DEBUG] Goal: org.apache.maven.plugins:maven-jar-plugin:3.5.0:jar (default-jar)
[DEBUG] Shutting down 'file-lock' factory
[DEBUG] Shutting down 'rwlock-local' factory
[DEBUG] Shutting down 'semaphore-local' factory
[DEBUG] Shutting down 'noop' factory

The first five lines are the machine and the tool: Apache Maven 3.9.16, the JDK it runs on and the locale. The [DEBUG] Goal: lines are the ones to search for when a build does something a pom does not mention, and the <configuration> block under each of them is the effective configuration of that goal, which is the effective pom narrowed to one execution.

-DskipTests and -Dmaven.test.skip

-DskipTests compiles the tests and does not run them: the classes are there for a later run, and surefire prints one line instead of a report.

mvn -B package -DskipTests > skip.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" skip.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ calc ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Nothing to compile - all classes are up to date.
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ calc ---
[INFO] Tests are skipped.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ calc ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

-Dmaven.test.skip=true is the stronger one: it skips the test compile too, so a test class that does not compile stops being a problem. The compiler says so in its own words:

mvn -B package -Dmaven.test.skip=true > noskip.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" noskip.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ calc ---
[INFO] Not compiling test sources
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ calc ---
[INFO] Tests are skipped.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ calc ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Neither switch belongs in a pom. A build that skips its tests by default is a build that ships untested code, and a reader cannot see from the jar whether the tests ran. They are for the command line: a packaging of a branch that is known red, a jar for a quick manual try, an emergency in a release. The surefire article shows the reports a skipped run does not write.

-Dtest

-Dtest narrows the run to the tests whose name matches. A class name, a class and a method with #, a wildcard, or several names separated by commas are all accepted; this is one method of one class:

mvn -B test -Dtest=CalcTest#addsTwoNumbers > one.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" one.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:calc >--------------------------
[INFO] Building calc 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.calc.CalcTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: <TIME> s -- in com.example.calc.CalcTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

One test instead of three, and the rest of the run unchanged: the compile steps still happen, because the test class has to exist before it can be selected. A name that matches nothing is not a failure of the selection but of the run: No tests to run. and a successful build, which is worth knowing before a CI job reports green for a filter with a typo in it.

-B

-B is batch mode, and every command of this course carries it. Without it Maven may ask a question on the terminal, which a script cannot answer, and it paints its output with ANSI colours and a progress bar that a captured log records as escape sequences. In batch mode there is no colour, no progress and no question: the output is the text a file can hold, which is what every log on these pages is.

The two switches that a beginner also meets are -o and -U: offline and update-snapshots. This image is offline through its settings file, so -o changes nothing here, and -U only matters for a repository that can be reached.

Where to go next

The dependency article starts the second half of the course, where the pom gains a library the code calls, and the surefire article takes the red run this page skipped.

Article author: Arthur Isaev