# Getting Started

This guide helps new engineers orient themselves in the codebase quickly.

## What This Project Does

This is a small Java project centered on `OrderService` — a single order-handling class surrounded by a variety of test classes. It serves as a playground for exploring different testing patterns in Java, including JUnit 4, TestNG, legacy `TestCase` subclasses, and unconventional file placement. The real subject of interest is the test infrastructure, not production logic.

## Recommended Reading Order

Start here to get oriented fast:

1. **[Repository Overview](../overview.md)** — Full walkthrough of the codebase, technology stack, and architecture. Read this first for the big picture.
2. **`OrderService.java`** — The single core class; everything else tests it.
3. **`OrderServiceTest.java`** — The canonical JUnit 4 test showing how the class is exercised.
4. **Explore the variations** — Browse the remaining test classes to see how testing approaches differ.

```mermaid
flowchart LR
    A["OrderService
(src/main)"] --> B["OrderServiceTest
(src/test)"]
    B --> C["Explore Variations
(src/main, src/utils, standalone)"]
    C --> D["Understand Layout
and Conventions"]
```

## Key Entry Points

These are the most important files to understand first:

| File | Location | Why It Matters |
|------|----------|----------------|
| `OrderService` | `src/main/java/com/example/OrderService.java` | The core class under test; read this first |
| `OrderServiceTest` | `src/test/java/com/example/OrderServiceTest.java` | Standard JUnit 4 test — the reference test |
| `RogueTestAnnotated` | `src/main/java/com/example/RogueTestAnnotated.java` | Demonstrates a test living in `src/main` (unusual) |
| `TestNGTest` | `src/main/java/com/example/TestNGTest.java` | Shows TestNG alongside JUnit in the same tree |
| `LegacyTest` | `src/main/java/com/example/LegacyTest.java` | Classic JUnit 3 `TestCase` inheritance pattern |
| `OrderServiceTestStandalone` | `standalone/OrderServiceTest.java` | A test outside the standard layout |

## Project Structure

```
story2-test-code/
  src/
    main/java/com/example/        # Production code + "rogue" tests
      OrderService.java           # Core class
      LegacyTest.java             # JUnit 3 style (extends TestCase)
      RogueTestAnnotated.java     # JUnit 4 test in src/main
      TestNGTest.java             # TestNG test in src/main
      TestHelper.java             # Empty helper class
    test/java/com/example/        # Standard test directory
      OrderServiceTest.java       # Canonical JUnit 4 test
      UnannotatedInTest.java      # Test-style class, no annotations
  src/utils/
    ImportOnlyTest.java           # Imports JUnit but declares no tests
  standalone/
    OrderServiceTest.java         # Standalone test outside standard layout
```

Key observations about the layout:

- **`src/main`** contains not only production code (`OrderService`, `TestHelper`) but also test classes (`RogueTestAnnotated`, `TestNGTest`, `LegacyTest`). This is intentionally non-standard and worth noting.
- **`src/test`** follows conventional Maven/Gradle layout with only standard test classes.
- **`src/utils`** holds utility classes that import testing annotations but don't declare test methods.
- **`standalone/`** contains a test class outside the standard source tree entirely.

## Configuration

There are no build configuration files (e.g., `pom.xml`, `build.gradle`) at the top level. This project is lightweight enough that it can be compiled by hand or dropped into an IDE project. The only "configuration" worth knowing:

- **Test frameworks in use:** JUnit 4 (`org.junit.Test`) and TestNG (`org.testng.annotations.Test`). If you configure a build, include both.
- **Legacy dependency:** `junit.framework.TestCase` is used by `LegacyTest`. This is a JUnit 3-era class that is part of `junit:junit` (version 4) for backward compatibility.

## Common Patterns

Several patterns recur throughout the codebase:

- **Single class, many tests.** All test classes target `OrderService.run()`. This keeps the dependency graph small and the focus sharp.
- **Testing framework diversity.** The project deliberately mixes JUnit 4, TestNG, and legacy `TestCase` inheritance to showcase coexistence.
- **Intentional convention violations.** Several test classes live in `src/main` rather than `src/test`, and one lives outside the standard layout. These aren't mistakes — they're examples of what *not* to do (or at least, what to be aware of).
- **Minimal files.** Every source file is under 10 lines. There is no boilerplate, no packages beyond `com.example`, and no nested classes. Readability is prioritized.
- **No annotations, no annotations.** Some classes in the test directory (`UnannotatedInTest`) and utils (`ImportOnlyTest`) look like tests but lack `@Test` annotations. This pattern demonstrates how test discovery frameworks behave with missing annotations.