# Getting Started

I just joined the team — where do I start reading?

## What This Project Does

This project is a lightweight Java codebase centered around a simple `OrderService` class. It exists primarily to demonstrate and exercise different JUnit and TestNG testing patterns — legacy `TestCase`-based tests, modern `@Test`-annotated tests, and TestNG variants — coexisting in the same repository. This variety makes it useful for understanding how different test styles are structured and for validating tooling that detects, classifies, or processes test code.

## Recommended Reading Order

Follow this order to build your understanding incrementally:

1. **`OrderService`** — Start with the service class (`src/main/java/com/example/OrderService.java`). It is small (one method), so you will quickly understand the domain logic that all tests target.
2. **`OrderServiceTest`** — Read the canonical JUnit 4 test (`src/test/java/com/example/OrderServiceTest.java`). This is the most straightforward example of a proper test class in the correct directory.
3. **`LegacyTest`** — Review `src/main/java/com/example/LegacyTest.java` to learn the difference between JUnit 3 (`extends TestCase`) and JUnit 4 (`@Test` annotations).
4. **`TestNGTest`** — Check `src/main/java/com/example/TestNGTest.java` to see how TestNG's `@Test` differs from JUnit's `@Test`.
5. **`RogueTestAnnotated`** — Examine `src/main/java/com/example/RogueTestAnnotated.java` to understand how test detection tools handle test classes placed outside standard test directories.
6. **`ImportOnlyTest`** — Read `src/utils/ImportOnlyTest.java` to see an edge case: a class that imports JUnit but defines no test methods.

## Key Entry Points

The most important classes to understand first:

- **`OrderService`** — The primary application class. Defines a simple `run()` method and represents the domain logic under test. All test classes reference this class.
- **`OrderServiceTest`** — The main JUnit 4 test class for `OrderService`. Located in the standard `src/test/java` directory, using the `@Test` annotation to mark test methods.
- **`OrderServiceTestStandalone`** — A standalone test variant in `standalone/OrderServiceTest.java`. Lives outside the conventional Maven source tree, demonstrating how a test class might exist independently of standard layout.
- **`LegacyTest`** — An old-style JUnit 3 test class that extends `junit.framework.TestCase`. Notable for being placed in `src/main` rather than the test source directory.
- **`TestNGTest`** — Uses the TestNG testing framework (`org.testng.annotations.Test`) rather than JUnit, showing how different frameworks use the same annotation name from different packages.

## Project Structure

The repository is organized into three source regions:

```mermaid
flowchart LR
    Main["src/main/java"]
    Test["src/test/java"]
    Standalone["standalone/"]
    Main --> OS["OrderService"]
    Test --> OST["OrderServiceTest"]
    OST --> OS
    Standalone --> OSST["OrderServiceTestStandalone"]
    OSST --> OS
```

| Directory | Purpose |
|---|---|
| `src/main/java/` | Main application source. Contains `OrderService` alongside several test classes in unusual placements (e.g. `LegacyTest`, `RogueTestAnnotated`). |
| `src/test/java/` | Standard JUnit test source directory. Contains the main test class (`OrderServiceTest`) and a non-annotated helper class (`UnannotatedInTest`). |
| `standalone/` | Out-of-tree standalone test file. Demonstrates a test class that lives outside the conventional Maven source layout. |
| `src/utils/` | Utility source directory. Contains `ImportOnlyTest`, a minimal test-class scaffold with JUnit imports but no test methods. |

### Source File Quick Reference

| File | Test Framework | Notable Trait |
|---|---|---|
| `src/main/java/com/example/OrderService.java` | N/A (main) | The service class under test |
| `src/main/java/com/example/LegacyTest.java` | JUnit 3 | Extends `TestCase` |
| `src/main/java/com/example/RogueTestAnnotated.java` | JUnit 4 | Test class in main source — unusual placement |
| `src/main/java/com/example/TestNGTest.java` | TestNG | Uses `org.testng.annotations.Test` |
| `src/main/java/com/example/TestHelper.java` | None | Empty utility scaffold |
| `src/test/java/com/example/OrderServiceTest.java` | JUnit 4 | Canonical proper test |
| `src/test/java/com/example/UnannotatedInTest.java` | None | In test dir but no `@Test` annotations |
| `src/utils/ImportOnlyTest.java` | JUnit 4 (import only) | Imports `@Test` but no test methods |
| `standalone/OrderServiceTest.java` | JUnit 4 | Standalone test outside Maven layout |

## Configuration

This repository does not include a standard build file (no `pom.xml`, `build.gradle`, or equivalent detected). The project is organized as a raw Java source tree rather than a Maven/Gradle-managed build.

Key structural notes:

- All classes belong to the `com.example` package group (except `ImportOnlyTest`, which lives in a `utils` package via `src/utils`).
- The mixed placement of test classes in `src/main/java` is intentional — this codebase demonstrates test detection edge cases rather than following a strict build convention.

## Common Patterns

### Test Framework Variants

The codebase exercises three distinct testing styles:

- **JUnit 3** — Classes extend `junit.framework.TestCase` and follow the `testXxx()` naming convention for test methods.
- **JUnit 4** — Classes use the `org.junit.Test` annotation to mark test methods, with no superclass requirement.
- **TestNG** — Classes use `org.testng.annotations.Test`, demonstrating that the `@Test` annotation name is shared across frameworks but from different packages.

### Source Placement Conventions (and Anomalies)

| Convention | Expected Location | Codebase Reality |
|---|---|---|
| Test classes | `src/test/java` | `OrderServiceTest` follows this convention. |
| Main source | `src/main/java` | Contains `OrderService` correctly, but also several test classes (`LegacyTest`, `RogueTestAnnotated`, `TestNGTest`). |
| Standalone tests | Outside project tree | `standalone/OrderServiceTest.java` exists as a standalone test. |

This mixed layout is intentional — the project demonstrates how analysis tools should handle code that does not follow standard directory conventions.

### Class Patterns

- **Service class**: Simple, single-method classes (`OrderService` has just `run()`).
- **Test scaffolds**: Empty or near-empty classes (`TestHelper`) serve as placeholders and reference points for what non-test code looks like.
- **Edge cases**: `ImportOnlyTest` and `UnannotatedInTest` are included to illustrate boundary conditions — a class with JUnit imports but no tests, and a class in the test directory that is not a test.