Demo: converting a project to Maven

Written Explanation

The starting point

Before conversion, the project looks like this (the IDE layout many beginners have, with sources and tests mixed together):

data-structures/
└── src/
    └── ds/
        ├── MyArrayList.java
        └── MyArrayListTest.java

MyArrayList stores ints in an array that grows when full, and MyArrayListTest has two JUnit tests: that adding five elements works past the starting capacity, and that get rejects a bad index with IndexOutOfBoundsException. The JUnit library was added through the IDE and lives in IDE settings, not in a file inside the project. That is exactly the "knowledge in somebody's head" problem from lesson 1.

The five steps

1. Create pom.xml at the project root with coordinates and the Java version.
2. Move sources to src/main/java and tests to src/test/java, keeping the package folders.
3. Planned mistake: leave the test class in src/main/java and see what breaks.
4. Add JUnit as a test dependency.
5. Run mvn test, add target/ to .gitignore, and commit.

Step 1: the pom.xml

Create the file next to the src folder. This is the whole file at this point:

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>data-structures</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
</project>

Choose your own groupId (a name you control, often a reversed domain; com.example is the conventional placeholder). Use the Java version of your JDK (21 here).

Step 2: move the files

Create src/main/java and src/test/java, then move the package folder ds (not just the files) so the package structure stays intact. Use your IDE's move or refactor tools if you prefer; they update nothing in the code here because the package names do not change. The resulting layout:

data-structures/
├── pom.xml
└── src/
    ├── main/java/ds/MyArrayList.java
    └── test/java/ds/MyArrayListTest.java

If you move files in the terminal, use the commands from module BEG-006 (mkdir, mv) and keep the ds/ folder name.

Step 3: the planned mistake

Suppose you moved everything into src/main/java, tests included, which is easy to do when you think "put the code in main". Run mvn test. Real output (trimmed):

[ERROR] COMPILATION ERROR :
[ERROR] .../src/main/java/ds/MyArrayListTest.java:[3,29] package org.junit.jupiter.api does not exist
[ERROR] .../src/main/java/ds/MyArrayListTest.java:[7,6] cannot find symbol

Two things to notice. First, the message complains about the JUnit import, which sends many learners to the wrong place: "I need to add JUnit!" Second, the file path in the message ends in src/main/java. That is the clue. Code in src/main/java is compiled without test libraries by design: the main code must not depend on testing tools.

To confirm that, we added the test-scoped JUnit dependency (step 4) while the test class was still in src/main/java, and ran mvn test again. The same error appeared: package org.junit.jupiter.api does not exist. The test scope really is invisible to main code, as lesson 3 promised.

The fix is to move the test class to src/test/java/ds/. Then the main tree contains only MyArrayList.java.

Step 4: add JUnit as a test dependency

Add this block to the pom.xml, after </properties>:

<dependencies>
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.12.2</version>
    <scope>test</scope>
  </dependency>
</dependencies>

(Check the current version on Maven Central, as in lesson 3. The version shown is the one used in this module's runs.) We also tried moving the test into src/test/java before adding the dependency: the error stayed the same, because the library was still missing. Both fixes are needed: right folder and right dependency.

Step 5: run it, ignore target/, commit

Now mvn test. Real output:

[INFO] Running ds.MyArrayListTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.105 s -- in ds.MyArrayListTest
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Two tests, as we wrote. The build created a target/ folder, which must stay out of version control (module BEG-046 introduced Git and branching). Create a file named .gitignore in the project root with this line:

target/

The trailing slash means "a folder". This is a plain text file; Git reads it and leaves target/ out of git status and out of commits. (I did not run Git in this demo, so the Git side of the check is described, not shown: after adding the line, run git status and confirm target/ is not listed before you commit pom.xml, .gitignore, and src/.)

The clean-machine check

The lab says "builds on a clean machine". You can approximate that without a second computer: copy only what is committed (pom.xml, .gitignore, src/, in a real project the output of git clone) into a new empty folder and run mvn test there. We did exactly this with a folder that contained those three items, and got Tests run: 2, Failures: 0 and BUILD SUCCESS. If it fails, something your build needs lives outside the repository: a JAR in your IDE settings, a file you forgot to commit, or a path that exists only on your machine. A truly clean machine also downloads the libraries again, since its local repository is empty, which needs internet access on the first build.

Where the analogy stops

Converting is not just "move files". The original project was held together by IDE settings you could not see; Maven's convention makes everything visible in a few text files, and that is the point. But Maven will not fix your code: if your tests were already failing, they still fail after the conversion.