# Getting Started

Welcome to the team. This guide helps you orient yourself quickly when you first start working in this codebase. If you are reading this for the first time, expect to understand a compact Java project that centers around a single service class and a suite of test harnesses exploring different testing frameworks and conventions.

## What This Project Does

This is a minimal Java codebase demonstrating various testing patterns and framework integrations. It features a single production class, `OrderService`, surrounded by test classes written using different conventions — from legacy JUnit 3 (`TestCase` subclass) through modern JUnit `@Test` annotations and TestNG's `@Test` annotation. It also includes a "rogue" class with test annotations placed in `main` (an unusual layout choice that draws attention) and a standalone test copy for reference. The project is framework-free — no Spring, Hibernate, or other application frameworks — so you can focus on core Java and testing conventions.

## Recommended Reading Order

Follow this order to build a mental model of the codebase without getting lost:

1. **`OrderService`** — The only production class. Start here to understand the core business logic.
2. **`OrderServiceTest`** — The conventional JUnit 4 test for `OrderService`. Shows how tests are structured and what behavior is expected.
3. **`TestHelper`** — A utility class for shared test fixtures. Currently empty but signals the intended location for shared test utilities.
4. **Explore the testing patterns** — Browse `LegacyTest` (JUnit 3), `TestNGTest` (TestNG), and `RogueTestAnnotated` to see how different frameworks and conventions are represented. Pay attention to where each class lives and what annotations it uses.
5. **Review the variants** — Check `ImportOnlyTest` and `UnannotatedInTest` for edge cases — classes that import test dependencies without providing test methods, or live in a test directory without annotations.
6. **The standalone copy** — Finally, peek at `standalone/OrderServiceTest.java` to see how the standalone variant compares to the canonical test.

## Key Entry Points

### `OrderService` — The Core Service

- **Location:** `src/main/java/com/example/OrderService.java`
- **Purpose:** The only production/business class in the project. Defines a `run()` method and serves as the primary class under test by `OrderServiceTest` and `OrderServiceTestStandalone`.
- **Why start here:** This is the anchor. All tests reference this class. Understanding it first gives you the context to make sense of everything else.

### `OrderServiceTest` — The Canonical Test

- **Location:** `src/test/java/com/example/OrderServiceTest.java`
- **Purpose:** JUnit 4-based test demonstrating the conventional testing approach for the service.
- **Why important:** Shows the expected behavior contract for `OrderService` and the standard JUnit 4 patterns used in the project.

### `TestHelper` — Shared Utilities

- **Location:** `src/main/java/com/example/TestHelper.java`
- **Purpose:** A plain utility class intended for shared test helpers or fixtures.
- **Why important:** Signals where shared test infrastructure should live, even though it currently contains no code.

### Other Notable Classes

| Class | Location | Framework | Notes |
|-------|----------|-----------|-------|
| `LegacyTest` | `src/main/java/com/example/LegacyTest.java` | JUnit 3 | Extends `junit.framework.TestCase`. Intentionally in `main` as a legacy pattern example. |
| `RogueTestAnnotated` | `src/main/java/com/example/RogueTestAnnotated.java` | JUnit 4 | Carries `@Test` annotation but lives in `src/main`. A code-smell example or placeholder to draw attention to test-location conventions. |
| `TestNGTest` | `src/main/java/com/example/TestNGTest.java` | TestNG | Uses `org.testng.annotations.Test`. Demonstrates TestNG integration. |
| `ImportOnlyTest` | `src/utils/ImportOnlyTest.java` | JUnit 4 | Imports `org.junit.Test` but declares no test methods. A stub demonstrating import-side effects. |
| `UnannotatedInTest` | `src/test/java/com/example/UnannotatedInTest.java` | None | Lives in test directory with a `run()` method but no annotations. Non-test helper or placeholder. |
| `OrderServiceTestStandalone` | `standalone/OrderServiceTest.java` | JUnit 4 | A standalone variant of `OrderServiceTest`, outside standard Maven layout. |

## Project Structure

The repository is organized into four logical source groups. All classes live under the `com.example` package.

```mermaid
flowchart TD
    subgraph main_src["Main Sources
src/main/java/com/example"]
        OS["OrderService"]
        LH["LegacyTest"]
        RT["RogueTestAnnotated"]
        TH["TestHelper"]
        TN["TestNGTest"]
    end

    subgraph test_src["Test Sources
src/test/java/com/example"]
        OST["OrderServiceTest"]
        UIT["UnannotatedInTest"]
    end

    subgraph utils["Utils
src/utils"]
        IOT["ImportOnlyTest"]
    end

    subgraph standalone["Standalone
standalone"]
        OSS["OrderServiceTestStandalone"]
    end

    OST --> OS
    RT --> JUNIT["JUnit"]
    OST --> JUNIT
    OSS --> JUNIT
    IOT --> JUNIT
    TN --> TESTNG["TestNG"]
    LH --> JUNIT3["JUnit 3"]
```

### Directory Breakdown

- **`src/main/java/com/example`** — Primary production source tree. `OrderService` is the only production class; the others are test utilities or experiments co-located in `main` rather than in a test scope.
- **`src/test/java/com/example`** — Conventional test directory. `OrderServiceTest` tests `OrderService`; `UnannotatedInTest` has no test framework annotations.
- **`src/utils`** — Small utility package containing `ImportOnlyTest`, which imports `org.junit.Test` but has no test methods.
- **`standalone`** — Standalone directory with a copy of an `OrderServiceTest` variant, used for isolated reference or experimentation.

## Configuration

This is a minimal, framework-free project. Key observations:

- **No build tool files detected** (no `pom.xml`, `build.gradle`, or `build.gradle.kts` in the current scope). If one exists outside the scanned area, use standard `mvn test` or `gradle test` commands to run tests.
- **No application frameworks** — No Spring, Hibernate, or other dependency-injection frameworks. The project depends only on the testing libraries themselves.
- **Testing framework dependencies** — The project uses three frameworks, which would need to be configured in a build file if one is added:
  - JUnit 3 via `junit.framework.TestCase` (for `LegacyTest`)
  - JUnit 4 via `org.junit.Test` (for `RogueTestAnnotated`, `OrderServiceTest`, `ImportOnlyTest`, `OrderServiceTestStandalone`)
  - TestNG via `org.testng.annotations.Test` (for `TestNGTest`)

## Common Patterns

### Testing Conventions

- **JUnit 4 is the primary test framework** — Most tests use `org.junit.Test` annotations.
- **TestNG is used alongside JUnit** — `TestNGTest` demonstrates that the project supports TestNG in addition to JUnit 4.
- **No consistent test class naming** — Some classes use `*Test` suffix (e.g., `OrderServiceTest`), others use descriptive names (e.g., `LegacyTest`, `RogueTestAnnotated`). Be aware of this inconsistency when searching for tests.

### Source Location Conventions

- **Production code lives in `src/main/java/com/example`** — This is the standard location.
- **Test code lives in `src/test/java/com/example`** — Standard Maven layout.
- **Some test classes are in `main`** — `LegacyTest`, `RogueTestAnnotated`, and `TestNGTest` are intentionally placed in `src/main` as demonstration or experimental code, not conventional tests.
- **A standalone copy exists** — `standalone/OrderServiceTest.java` is a duplicate variant outside standard source directories.

### Class Design Patterns

- **Minimal classes** — All classes are small (30–90 lines). `TestHelper` has no methods; `ImportOnlyTest` imports a dependency without using it. This makes the codebase easy to scan but means many classes are placeholders or experiments rather than production-ready code.
- **No inheritance hierarchies** — The only inheritance is `LegacyTest` extending `junit.framework.TestCase`. No custom base classes or interfaces are used.
- **No package-private or protected members** — Classes appear to be public with no visibility modifiers beyond default class access.

### Code Style Notes

- **Single package** — Everything lives under `com.example`. No sub-packages beyond `com.example`.
- **No comments or Javadoc** — Classes have no inline documentation. Rely on the wiki pages and this guide for context.
- **No imports beyond test frameworks** — Classes only import the testing libraries they use. No logging, I/O, or utility imports.

## Next Steps

After reading through this guide:

1. Open `src/main/java/com/example/OrderService.java` and read it top to bottom.
2. Open `src/test/java/com/example/OrderServiceTest.java` and trace through the test assertions.
3. Check the [Repository Overview](/wiki/overview.md) for a full architectural breakdown.
4. If you plan to add a new test or feature, start by reviewing how existing tests are structured — particularly `OrderServiceTest` as the canonical example.