Packages, Class Diagrams and Unit Tests in Java

A package groups related classes and interfaces under one name. It also separates names: two classes called Parcel can coexist when their package names differ. A package gives Java an access boundary as well as a way to organize files.

Declare the package first

An ordinary source file begins with its package declaration, followed by imports and then the class. Comments can appear before the declaration. For example:

package com.example.parcels.domain;

public class Parcel {
    private int weightGrams;

    public Parcel(int weightGrams) {
        this.weightGrams = weightGrams;
    }
}

Every top-level type in that file belongs to com.example.parcels.domain. A file has at most one package declaration. The public class Parcel belongs in Parcel.java; changing the folder alone does not change the declared package.

Turn dots into folders

The source root is the folder where the package path begins. In a standard Maven or Gradle project, main Java code starts at src/main/java. Replace each dot in the package name with a slash, then add the class name:

src/main/java/
  com/example/parcels/domain/Parcel.java

The package is com.example.parcels.domain, not src.main.java.com.example.parcels.domain. The first three folders describe the build layout; they are not part of the Java name. When an IDE reports a package mismatch, compare the declaration with the path below the source root. Move the file or correct the declaration so they agree.

Package names use lowercase letters. Organizations commonly reverse their domain: example.com becomes com.example, followed by the project and its area. A project without a domain can use parcels.domain. If a reversed domain component contains a hyphen, replace it with an underscore, as in org.example.hyphenated_name. Avoid the platform's java and javax naming space.

Use the complete class name

A fully qualified name joins the package and simple class name: com.example.parcels.domain.Parcel. It identifies the class even when another package also has a Parcel. Code can name an accessible class in full without an import:

java.util.ArrayList<String> names = new java.util.ArrayList<>();

To run a packaged main class, give its full name and a classpath pointing to the root of the compiled package tree. From the project folder:

javac -d out src/main/java/com/example/parcels/Main.java src/main/java/com/example/parcels/domain/Parcel.java
java -cp out com.example.parcels.Main

Here javac -d out creates the output tree, and java -cp out searches from that tree's root. Starting java Main from a package folder loses the package portion of the class's identity. Build tools and IDEs normally manage these commands.

Distinguish neighboring packages

com.example.parcels and com.example.parcels.domain are separate packages. Sharing a name prefix gives no extra access rights. A file with no declaration belongs to the unnamed package. Named packages cannot import its classes, so use named packages throughout a program with several parts.

An import lets one source file use an accessible type's simple name. It tells the compiler what the name means. It does not copy the class, download a library, or make a hidden class public.

Read the top of a source file

The UI belongs to one package and uses classes from two others:

package com.example.parcels.ui;

import com.example.parcels.domain.Parcel;
import com.example.parcels.domain.ShippingCalculator;
import java.util.Scanner;

public class TextUI {
    private Scanner scanner;
    private ShippingCalculator calculator;
}

Parcel and ShippingCalculator come from the program's domain package; Scanner comes from the Java library. Each import applies only to this file. Another file that uses Scanner needs its own import or the full name java.util.Scanner.

Choose a single type or a wildcard

import java.util.Scanner; is a single-type import. Its exact class is visible to the reader. import java.util.*; is an import on demand: accessible types in that package can be named when used. The wildcard does not load unused classes into the program or slow it down.

The wildcard stops at that package. It does not include java.util.function.Function or java.util.stream.Collectors, which live in separate packages. The same rule applies to your own code: import com.example.parcels.*; does not reach com.example.parcels.domain.Parcel.

Three cases need no import: types in the same package, automatically available types in java.lang, and types named in full. That is why String, System, Math, Integer, and Object commonly appear without imports.

Resolve a shared simple name

Both java.util and java.awt have a class called List. Two single-type imports for these different classes are a compile error. Two wildcard imports can coexist, but the simple name List becomes ambiguous when used. A single-type import takes precedence over a wildcard import.

If both classes are needed, import one and spell out the other:

import java.util.List;

class NameDisplay {
    private List<String> names;
    private java.awt.List widget;
}

Java imports provide no alias syntax such as import ... as .... The fully qualified name is the way to distinguish the second type.

Import a static member

A static import removes the owning class name from a static member call:

import static java.lang.Math.sqrt;

The file can now call sqrt(16.0). Test code often uses import static org.junit.jupiter.api.Assertions.assertEquals; so assertions read as direct checks. In ordinary program code, use static imports selectively so readers can still see where operations come from.

Follow what the error says

“Cannot find symbol” can mean a missing import or a misspelled type. “Package ... does not exist” points toward a package spelling, source-root, or dependency problem. “Is not public ... cannot be accessed from outside package” means Java found the type but access is blocked. Adding another import cannot fix that access error; inspect the class declaration and the members you need.

A package should expose the classes and methods other parts need while keeping implementation details hidden. Access modifiers make that boundary enforceable. An import can shorten a name, but it cannot cross a boundary that Java access rules close.

Choose access for a class member

No modifier means package-private for ordinary class members and constructors. It is not a keyword called default. A top-level class has only two choices: public or package-private. A public top-level class is stored in a file with its name, such as ShippingCalculator.java.

Check the type and the operation

Suppose the UI must construct a parcel. A public class alone is insufficient:

package com.example.parcels.domain;

public class Parcel {
    private int weightGrams;

    Parcel(int weightGrams) {
        this.weightGrams = weightGrams;
    }
}

The constructor has package access. Code in com.example.parcels.ui can name Parcel, but cannot call new Parcel(1200). Make that constructor public if creating parcels is part of the package's public service. Keep weightGrams private and expose an appropriate operation instead of opening the field.

Package-private access compares the whole package name. Neither a parent-looking package nor a child-looking package is the same package. Code in com.example.parcels gets no special access to helpers in com.example.parcels.domain.

Understand protected access

protected allows access from unrelated classes in the declaring package as well as from subclasses. Across packages, an instance member is accessed through the subclass's inheritance context. A subclass can use its own inherited field, but cannot use an arbitrary superclass object as a way around the package boundary.

For example, if Item declares protected int weightGrams, a Letter extends Item in another package can use this.weightGrams. Inside Letter, a parameter typed merely as Item does not permit item.weightGrams; a reference typed as Letter does permit the inherited access. This restriction keeps subclass privileges from becoming general access to every Item.

Hide helpers deliberately

Make ShippingCalculator and feeInCents public if the UI calls them. A supporting WeightBands class can remain package-private. Code outside the domain package then depends on the calculator's behavior, not on how it stores the table. Replacing that helper requires fewer changes elsewhere.

Tests can use the same package name as the class they test while living under src/test/java. This gives them package access without placing test code among production files. It does not grant access to private fields. Making every member public just to satisfy a test spreads dependencies on internals; test public behavior or a useful package-level operation instead.

A UML class diagram shows static structure: classes, their members, and relationships. It helps a reader see what kinds of objects exist and what they offer. It does not trace the order of method calls during execution.

Read the three compartments

A class box has the class name at the top, attributes in the middle, and operations at the bottom. An attribute usually represents a Java field; an operation represents a method's visible signature. A sketch can omit compartments that do not serve its purpose.

For a parcel, a textual rendering of the box is:

Parcel
-----------------------------
- weightGrams: int
- recipient: String
-----------------------------
+ Parcel(weightGrams: int, recipient: String)
+ getWeightGrams(): int
+ isHeavierThan(limitGrams: int): boolean

The constructor has the class's name and no return type. The method isHeavierThan accepts an integer named limitGrams and returns a boolean.

Translate the order of names and types

UML puts the name before the type: weightGrams: int. Java puts the type first: int weightGrams. An operation follows the same name-first pattern for parameters, then puts the return type after its closing parenthesis.

private int weightGrams;

public boolean isHeavierThan(int limitGrams) {
    return weightGrams > limitGrams;
}

This code corresponds to - weightGrams: int and + isHeavierThan(limitGrams: int): boolean. A method body is usually absent from the diagram; the operation states what can be called, not the algorithm.

Preserve visibility and special markings

The visibility signs are + public, - private, # protected, and ~ package access. Put the sign before the member name. If a supplied diagram omits a sign, do not invent its visibility; add the intended sign when documenting code.

A static member is underlined. It belongs to the class rather than to each object. An abstract class or operation is italicized, or marked {abstract} when italics are inconvenient. The abstract marking means a subclass must supply missing behavior before an object can be created from a concrete class.

An interface box carries «interface» above its name. For example, ParcelRepository can offer + save(parcel: Parcel): void and + findAll(): List<Parcel>. The box states a contract; it does not choose a storage implementation.

Choose the detail the reader needs

A planning sketch might show just Parcel, Shipment, and their main operations. A diagram for implementing a class needs types and visibility. Listing every routine getter can hide the relationships the diagram was meant to show. Select useful members and keep them consistent with the code: a private Java field should not appear with a public + sign, and a static method needs its underline.

An association shows a structural link between objects. In Java, one object commonly keeps a reference to another in a field. The line can also show how many objects are allowed and which direction the reference can be followed.

Count from the opposite end

Multiplicity sits beside the class it counts. If 1..* appears beside Parcel and 1 beside Shipment, one shipment has one or more parcels, and each parcel belongs to exactly one shipment. Read each end separately, starting from one object at the opposite end.

A single reference can represent 1 or 0..1; a collection represents a many-valued end. A Java List alone does not enforce a lower bound. A Shipment with a 1..* parcel rule must reject an empty initial list and prevent later operations from leaving it empty. Likewise, a required single reference needs a check against null.

Follow the reference

An open arrowhead at Parcel means a reference can be followed from Shipment to Parcel. A class diagram can leave navigability unspecified. In the teaching convention used here, arrows mark one-way references; an unadorned line may mean bidirectional access or unspecified direction. Do not infer a reverse field solely from an arrow toward Parcel.

A role name such as parcels labels what the link means from the shipment. Show that reference either as an association or as - parcels: List<Parcel> in the box. Displaying both without a reason can make one field look like two different pieces of state.

Choose the whole–part meaning

Composition uses a filled diamond at the whole. A part belongs to at most one composite whole at a time and is normally removed with that whole, as an order and its order lines. Aggregation uses a hollow diamond for a looser grouping whose parts can exist independently. A team can group players without owning their lifetimes.

Java has no diamond keyword and does not enforce UML ownership just because a list exists. Model composition only when the design includes that ownership rule. When the design simply says one object knows another, a plain association is clearer than an unsupported diamond.

Show a use without claiming ownership

A dependency is a dashed line with an open arrowhead toward the type being used. A calculator with feeInCents(Parcel parcel) depends on Parcel because its method signature uses that type. A dependency is a general use relationship; it is not limited to code without fields. An association gives more specific structural information when a field is important to the model.

Before drawing a line, ask what the code or requirement establishes: a reference, an allowed count, a use, or ownership. A collection establishes many-valued storage, but it does not by itself establish exclusive ownership or a minimum count.

Inheritance and interface implementation both connect a specific type to a more general one. UML uses a hollow triangle at the general type, but the line style distinguishes the two relationships. That distinction tells you which Java declaration to write.

Read the triangle and its line

A solid line with a hollow triangle at Item means a subclass such as Letter extends Item. This is generalization. A dashed line with a hollow triangle at ParcelRepository means a class such as InMemoryParcelRepository implements that interface. This is realization.

The triangle always touches the superclass or interface. A dashed open arrow, without the triangle, means dependency instead. Line style and arrowhead together carry the meaning; a dashed line alone is insufficient.

Build the skeleton in a useful order

1. Create each class or interface in its package.
2. Translate attributes into fields, preserving names, types, and visibility.
3. Translate navigable associations into reference or collection fields.
4. Add extends or implements from the generalization or realization lines.
5. Translate operations into method headers and then supply their bodies.

Suppose an interface offers save and findAll. An implementation has a many-valued association to Parcel with role parcels:

public class InMemoryParcelRepository implements ParcelRepository {
    private List<Parcel> parcels = new ArrayList<>();

    @Override
    public void save(Parcel parcel) {
        parcels.add(parcel);
    }

    @Override
    public List<Parcel> findAll() {
        return new ArrayList<>(parcels);
    }
}

The dashed triangle supplies implements ParcelRepository. The association supplies the list field. The operation signatures supply the two public methods. The method bodies are an implementation choice: here save appends an object, and findAll returns a new list so callers cannot directly add or remove entries in the stored list. The parcel objects themselves are still shared.

Draw the other direction

Start with one box for each class or interface. A simple-value field becomes an attribute. A reference to a class in the program becomes an association; a collection suggests a many-valued end. Inspect constructor and method checks before claiming a lower bound of one. Translate extends into a solid triangle line and implements into a dashed triangle line.

Inherited fields and operations usually stay in the superclass box. Put new or overridden members in the subclass. Add a dependency for a parameter, return type, or local use when that relationship helps explain the design.

Packages can surround their classes in folder-shaped boxes with a small tab. These groups help reveal which areas depend on which others. Keep a documentation diagram current when code changes; label an early planning sketch so readers understand its purpose.

A Shipment that contains parcels is not a kind of Parcel. Its list gives a “has” relationship, so draw an association. Use inheritance for an “is a kind of” relationship that the Java type system and behavior actually support.

The user interface reads commands and displays results. The application logic holds the rules and data those commands act on. Separating them lets a test call a calculation directly, and lets another interface reuse it without copying the rule.

Give each part a clear job

TextUI owns the conversation: ask for a weight, read a line with Scanner, turn the text into a number, call the logic, and print the result. ShippingCalculator accepts a weight in grams and returns a fee in cents. It does not ask the user anything or print an answer.

A method called printFee mixes those jobs if it both calculates and prints. Change the logic operation to feeInCents(int weightGrams). The UI can then print "Fee: " + calculator.feeInCents(weightGrams) + " cents". A test can assert the returned integer without capturing console output.

Write the rule as a return value

The parcel rule charges 500 cents for positive weights through 2,000 g, 900 cents through 10,000 g, then 100 additional cents for every started 1,000 g above 10,000 g.

public int feeInCents(int weightGrams) {
    if (weightGrams <= 0) {
        throw new IllegalArgumentException("weight must be positive");
    }
    if (weightGrams <= 2000) {
        return 500;
    }
    if (weightGrams <= 10000) {
        return 900;
    }
    long excess = (long) weightGrams - 10000;
    long startedBlocks = (excess + 999) / 1000;
    return (int) (900 + 100 * startedBlocks);
}

The first two successful branches include their upper boundaries. For 12,500 g, the excess is 2,500 g. Integer division after adding 999 counts three started blocks, giving 1,200 cents. The intermediate long arithmetic also handles large positive int weights without overflowing when 999 is added.

An invalid weight raises an IllegalArgumentException: the method rejects an argument that violates its rule. The UI can catch that exception and choose a readable message. The rule belongs to the logic; the wording of the message belongs to the interface.

Connect the objects in main

Pass the input reader and calculator into the UI constructor:

public static void main(String[] args) {
    Scanner scanner = new Scanner(System.in);
    ShippingCalculator calculator = new ShippingCalculator();
    TextUI ui = new TextUI(scanner, calculator);
    ui.start();
}

Create one scanner for the input stream and share it with the UI. Multiple scanners over System.in can interfere with each other's buffered input. The main method assembles the program; start runs the dialog loop.

When reviewing a class, look for its responsibilities. A Scanner or System.out inside a fee calculator reveals mixed input/output and rules. A fee formula inside the UI reveals the same problem from the other side. Move the calculation into a method with explicit input and a result; keep command parsing and display text together in the UI.

A layered program groups classes by responsibility. The presentation layer handles the dialog, the logic layer applies rules, and the data access layer saves and retrieves information. A class uses another layer through a clear operation instead of reaching into its internal fields.

Place the parcel classes

The UI package contains TextUI. The domain package contains Parcel, ShippingCalculator, and ParcelService. The data package contains ParcelRepository and its storage implementations. Main assembles the objects above these layers.

A command follows this route: the user enters "add 1200 Alex"; the UI parses it and calls service.register(1200, "Alex"); the service validates the weight, creates a parcel, saves it through the repository, and returns 500 cents; the UI prints the fee. Reading text, deciding what is allowed, and storing the result have separate homes.

Depend on a contract

The service needs storage behavior, not a particular file format. Express that behavior through an interface:

public interface ParcelRepository {
    void save(Parcel parcel);
    List<Parcel> findAll();
}

The service stores a reference typed as ParcelRepository and receives it in the constructor:

public class ParcelService {
    private final ParcelRepository repository;

    public ParcelService(ParcelRepository repository) {
        this.repository = repository;
    }
}

This is constructor injection, a form of dependency injection: the caller provides a collaborator. A service that constructs new FileParcelRepository(...) inside its own methods chooses file storage for itself and makes isolated tests harder.

Change the implementation at assembly

The running program can create new ParcelService(new FileParcelRepository("parcels.csv")). A test can supply new InMemoryParcelRepository(). Both implementations satisfy the same interface. Calls through the interface use polymorphism to reach the actual object's methods.

With the repository contract unchanged, switching storage requires a new implementation and a change at assembly. Fee rules and dialog code do not need to know how the data is stored.

Check dependency direction precisely

The downward service-use path is UI to logic to storage. The domain must not import or call UI classes. If the logic needs to tell the user a result, return it to the UI. If the UI saves directly through the repository, it can bypass the service's validation.

Java type references also matter: a repository signature that names Parcel depends on that domain type. With ParcelRepository in the data package and the service in the domain package, those packages refer to each other. To remove that package cycle, place the repository interface beside the domain types and let the data implementations import it. The service still uses the same contract; only its home changes. Read both the method-call route and the imports when checking the design.

Larger programs may first group packages by feature, such as orders or customers, and then separate responsibilities within each feature. Package names help readers locate responsibilities; constructor parameters and method signatures show the actual dependencies.

A unit test calls a small unit of code with chosen input and checks the result automatically. It makes a requirement executable. Rerunning tests after a change helps find a regression, a bug in behavior that worked before.

Create a Jupiter test

JUnit Jupiter is the programming model used by JUnit 5 and 6. JUnit 6 needs Java 17 or later. Test annotations and assertions use org.junit.jupiter.api.

Place ShippingCalculatorTest.java under src/test/java/com/example/parcels/domain, with the same package declaration as the calculator. The separate source root keeps tests apart from delivered program code while retaining same-package access.

package com.example.parcels.domain;

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;

class ShippingCalculatorTest {
    @Test
    void lightParcelCostsBaseFee() {
        ShippingCalculator calculator = new ShippingCalculator();

        int fee = calculator.feeInCents(1500);

        assertEquals(500, fee);
    }
}

The test class and method can be package-private. A test method returns void and must not be private. Use Jupiter's @Test; JUnit 4's org.junit.Test belongs to a different programming model and is not discovered by the Jupiter engine. JUnit 4 assertions can work when their library is available, but consistent Jupiter imports keep the setup clear.

Read arrange–act–assert

The first part arranges a calculator. The second acts by asking for the fee. The final assertion compares the expected 500 cents with the returned value. Blank lines make these jobs easy to spot. Printing fee alone would leave a person to decide whether it was correct; the assertion makes that decision part of the test.

assertEquals(expected, actual) puts the requirement first and the observed result second. An optional message comes last, as in assertEquals(500, fee, "fee for 1,500 g"). Reversing the first two arguments usually preserves pass/fail for these values but reverses the meaning of the failure report.

Choose the right assertion

Use assertTrue or assertFalse for a boolean, and assertNull or assertNotNull when the presence of an object is the outcome. Object equality checks use equals; without an override, two distinct objects with matching fields may still compare unequal.

Floating-point results need an appropriate tolerance. The calculation 0.1 + 0.2 produces 0.30000000000000004 in a Java double:

assertEquals(0.3, 0.1 + 0.2, 1e-9);

The third argument allows an absolute difference up to 0.000000001. Select a tolerance that fits the calculation; an overly large tolerance can hide a meaningful error. Integer cent calculations need no decimal tolerance.

Read a failure

Run a test from the IDE or the build tool. A report such as "expected: <500> but was: <900>" names the required and observed results; the stack trace points to the assertion. An unexpected exception also fails a test. Green means the checked cases passed; choosing those cases remains a separate part of testing.

A useful test set checks how the specification divides inputs into cases. One ordinary input rarely tests a whole rule. Boundary cases at a limit and just beside it are especially good at finding a condition written with the wrong comparison operator.

Partition the input space

An equivalence class groups inputs that should be treated alike. The shipping rule has invalid weights at zero or below, a 500-cent band through 2,000 g, a 900-cent band through 10,000 g, and a started-block calculation above that. Pick representative inputs from the classes, then inspect their boundaries.

Changing <= 2000 to < 2000 affects exactly 2,000 g. A test at 1,500 g still passes. Above 10,000 g, test both a whole block and the first gram of the next block to check rounding upward.

Expected values come from the requirement and hand calculation. For 12,500 g, the excess is 2,500 g, requiring three started blocks, so the expected result is 1,200 cents. Running the method and copying its answer into the test would also copy any bug.

Test rejected input

An exception test gives JUnit the operation to run:

assertThrows(IllegalArgumentException.class,
    () -> calculator.feeInCents(0));

The () -> ... expression is a lambda: a small piece of code handed to JUnit. JUnit executes it inside the check. Calling the method before handing it to the assertion would let the exception escape before the check could inspect it.

assertThrows accepts the named exception type or a subclass. It fails if the operation completes normally or throws an incompatible type. It returns the exception, so a required message can be checked:

IllegalArgumentException error = assertThrows(
    IllegalArgumentException.class,
    () -> calculator.feeInCents(0));
assertEquals("weight must be positive", error.getMessage());

Give one scenario a readable name

Names such as zeroWeightIsRejected and feeIsBaseFeeAtExactly2000Grams identify the intended behavior. A test can have several assertions when they check the same outcome. After adding parcels of 1,200 g and 800 g to a shipment, checking a count of two and a total weight of 2,000 g describes that one scenario. assertAll can group checks so all failures are reported.

Check changed objects through their behavior, such as parcelCount() and totalWeightGrams(), instead of exposing private fields for tests. A refactoring can then change storage details while preserving the checks. Full line coverage means the tests executed the lines; it can still miss a wrong boundary or an untested invalid input.

Each test should arrange everything it needs. A test that passes only after another test has added data depends on hidden history. Such tests become hard to trust when a runner changes the order or runs just one method.

Create a fresh fixture

A fixture is the set of objects and data a test uses. Put repeated per-test setup in @BeforeEach:

class ShipmentTest {
    private Shipment shipment;

    @BeforeEach
    void setUp() {
        shipment = new Shipment();
    }

    @Test
    void newShipmentIsEmpty() {
        assertEquals(0, shipment.parcelCount());
    }

    @Test
    void addingParcelIncreasesCount() {
        shipment.add(new Parcel(1200, "Alex"));
        assertEquals(1, shipment.parcelCount());
    }
}

The setup runs before each method. The second test does not alter the shipment used by the first. By default, Jupiter also creates a new test-class instance for each test method. Mutable static fields remain shared, so a static list can still leak state across those instances.

@AfterEach performs per-test cleanup. @BeforeAll and @AfterAll run once for the class and are static under the default lifecycle. Shared read-only reference data can suit once-per-class setup; changing objects usually need fresh per-test construction. Tests must work individually without depending on source-file order.

Use one test body for a table

A parameterized test runs the same behavior check for several rows:

@ParameterizedTest
@CsvSource({"1, 500", "2000, 500", "2001, 900",
            "10000, 900", "10001, 1000"})
void feeMatchesTable(int grams, int expected) {
    assertEquals(expected,
        new ShippingCalculator().feeInCents(grams));
}

Each row is a separate invocation with its own report. @ValueSource(ints = {0, -5}) supplies one integer per invocation for invalid-input tests. Parameterized annotations come from org.junit.jupiter.params; CsvSource and ValueSource are in its provider package. The junit-jupiter aggregate dependency includes the parameterized-test module.

@DisplayName adds a readable report label. @Disabled records a skipped test with a reason; a skipped check provides no passing evidence for the behavior it would test.

Control the environment

A service test can receive an InMemoryParcelRepository, a working fake that stores parcels in memory. This avoids real file contents and isolates the logic. Pass a Scanner built from a known string to a text UI when testing its input handling. A fixed date or a Random with a fixed seed similarly makes an outside input predictable.

A flaky test changes its result across runs without a relevant code change. Shared mutable data, the current time, uncontrolled random values, and leftover files are common causes. Give the test control of those inputs. Keep helpers small and setup readable; a fixture that constructs many unrelated objects can reveal that the tested class has too many jobs.

Test-driven development (TDD) starts a behavior change with a test. A short cycle makes the missing behavior visible, implements it, and then improves the code's structure. A test list holds cases still to explore without requiring them all to be written at once.

Take one item from the test list

For a Gregorian leap-year checker, list four behaviors: an ordinary non-leap year, a year divisible by four, a century that is not divisible by 400, and a century that is divisible by 400. These cases represent different parts of the rule.

Red: write one test and run it. A missing method may cause a compile error. Once the method exists, verify that the test fails for the behavior you intend to add. A missing assertion, the wrong method call, or an undiscovered test can make an apparent green result misleading. A new case may also already be satisfied by existing code; inspect that result before changing the implementation.

Green: add the simplest code that passes the new test and all previous tests. Refactor: improve structure without changing behavior, rerunning tests after each small change. Then choose the next case.

Let cases develop the rule

The first check is assertFalse(LeapYears.isLeapYear(2023)). Creating the method with return false; passes this case. It is a deliberate first step, not a finished calendar rule.

The next check, assertTrue(LeapYears.isLeapYear(2024)), fails. Change the method to return year % 4 == 0;. Both cases now pass.

Next, assertFalse(LeapYears.isLeapYear(1900)) exposes the century exception. Changing the expression to year % 4 == 0 && year % 100 != 0 makes those three tests pass.

Finally, assertTrue(LeapYears.isLeapYear(2000)) exposes the exception to the century rule. The implementation becomes:

public static boolean isLeapYear(int year) {
    return year % 400 == 0
        || (year % 4 == 0 && year % 100 != 0);
}

Run all four checks after the change. Each new failure pointed to one missing part of the behavior instead of asking you to debug a large unfinished implementation.

Improve structure while green

Refactoring changes names or organization while preserving behavior. Renaming a method, extracting a helper, removing repeated logic, and moving a class to a better package are refactorings when observable behavior stays the same. Changing the fee charged at a boundary is a behavior change and needs a test describing that change.

If a cleanup breaks a test, restore the intended behavior before adding another feature. Small changes help locate the cause of a failure. Skipping cleanup leaves passing code that becomes harder to extend; writing a large implementation for many future cases creates more code to inspect when the next check fails.

TDD depends on the quality of the requirements and selected cases. A misunderstood rule can appear in both the test and implementation. Logic with clear inputs and outputs is a useful starting point because the expected result can be stated independently and checked quickly.

A build tool turns source files into a checked, packaged result. Maven reads a project description, downloads declared libraries, compiles code, runs tests, and creates an artifact. The same description gives the command line and IDE a shared view of the project.

Use the standard layout

Put production Java code in src/main/java, tests in src/test/java, production resources in src/main/resources, and test data in src/test/resources. Package folders begin below each Java source root. Maven writes generated output under target; edit the sources, not the compiled copies in that folder.

The project-root file pom.xml, the Project Object Model, identifies the project using coordinates: groupId, artifactId, and version. For example, com.example:parcels:1.0-SNAPSHOT identifies a development version of the parcel program. A library dependency has coordinates too.

Declare JUnit for tests

The following is a complete small Maven configuration. It compiles for Java 17 and selects a test runner that supports Jupiter:

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>parcels</artifactId>
  <version>1.0-SNAPSHOT</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>6.1.3</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.4</version>
      </plugin>
    </plugins>
  </build>
</project>

Maven retrieves dependencies from repositories, normally Maven Central, and caches them in .m2/repository under your home folder. Libraries needed by a dependency are transitive dependencies. Test scope makes JUnit available for compiling and running tests, not for main-code compilation or the program's runtime classpath. An ordinary JAR keeps its dependency JARs separate unless packaging is configured to bundle them.

Ask for a lifecycle phase

The main lifecycle progresses through compile, test, package, and install among other phases. Asking for package runs earlier phases too. With the wrapper, ./mvnw test compiles and tests; ./mvnw package also creates the JAR under target; ./mvnw install additionally places the artifact in the local repository. The separate clean lifecycle, ./mvnw clean, removes generated output.

A test failure stops the normal build before packaging a new artifact. An older JAR may still be present until cleaned, so its presence does not establish that the latest build passed.

Make test discovery visible

Surefire's default patterns include names starting with Test or ending with Test, Tests, or TestCase. ShippingChecks does not match them; use ShippingCalculatorTest and inspect the reported test count. Tests placed under src/main/java cannot use a test-scoped dependency.

The Maven Wrapper, mvnw or Windows mvnw.cmd, runs the project-specified Maven version. Use a project that includes its wrapper files; a POM by itself does not create the scripts. From its root, the wrapper provides a consistent build command without a separate Maven installation.

Gradle describes a build with a script and executes tasks with their dependencies. A Kotlin script is named build.gradle.kts; a Groovy script is named build.gradle. Plugins supply tasks, and dependency configurations state where libraries are needed.

Configure an application and Jupiter

A project-root settings.gradle.kts can contain rootProject.name = "parcels". A matching Kotlin build script is:

plugins {
    application
}

repositories {
    mavenCentral()
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

dependencies {
    testImplementation(platform("org.junit:junit-bom:6.1.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

application {
    mainClass = "com.example.parcels.Main"
}

tasks.test {
    useJUnitPlatform()
}

The application plugin supplies Java build tasks and adds run. mavenCentral() selects a dependency repository. The BOM, or bill of materials, aligns JUnit module versions, so the version appears once. testImplementation supplies libraries needed to compile and run tests. testRuntimeOnly supplies the launcher only when running them. Main-code libraries use implementation, which also makes them available to test code.

useJUnitPlatform() selects the platform that runs Jupiter tests. Adding Jupiter libraries without configuring the runner can leave those tests undiscovered. Current Gradle fails when test sources exist but no tests are discovered under its default setting; inspect the test task output and configuration instead of removing the check.

Run tasks with the wrapper

Use the wrapper included with the project: ./gradlew test runs tests; ./gradlew build compiles, tests, and packages; ./gradlew run starts the configured main class; and ./gradlew clean removes build. Windows uses gradlew.bat. Gradle uses the same main/test source layout as Maven and writes generated output to build.

A task marked UP-TO-DATE has unchanged tracked inputs and outputs, so Gradle reuses its previous result. That message differs from a newly executed test run. The HTML test report is build/reports/tests/test/index.html.

Find the stage that failed

Start with the earliest useful error. “Cannot find symbol” during main compilation points to the named code, import, or dependency. Missing org.junit.jupiter.api during test compilation points to test dependency setup; the same error during main compilation can mean a test was put in the main source folder. A dependency resolution error points toward coordinates, repository access, or network availability.

A running test failure is different: the test was compiled and discovered, but its check failed. If "expected: <500> but was: <900>" appears at the 2,000 g fee boundary, inspect the comparison that chooses the band. Changing dependencies will not repair that calculation.

Maven offers a declarative XML description with fixed lifecycle phases. Gradle offers configurable scripts and tasks, including skipping work that is up to date. Both automate repeatable Java builds; use the tool chosen for the project and read its first actionable failure before changing code.