# Getting Started

Welcome to the team! If you just checked out this codebase and are wondering where to begin, this guide will orient you in under five minutes.

## What This Project Does

This is a lightweight Java project that explores different testing paradigms and framework integrations. At its core sits an `OrderService` class surrounded by test classes written in multiple styles -- JUnit 4 (`TestCase` inheritance), JUnit 5 (annotation-based), and TestNG. The project also demonstrates edge cases in source layout, such as annotated test classes placed in the main source directory, utility classes with import-only references, and standalone tests outside the standard `src/` tree.

If you're looking for a full application or production framework, you won't find one here. This codebase is intentionally minimal -- it exists to demonstrate and compare how different Java testing approaches behave.

## Recommended Reading Order

Follow this sequence to build a mental model of the codebase from the inside out:

1. **[OrderService.java](src/main/java/com/example/OrderService.java)** -- The single production class. This is the core business logic the entire project revolves around. Read it first.
2. **[OrderServiceTest.java](src/test/java/com/example/OrderServiceTest.java)** -- The primary unit tests for `OrderService`. This is the best reference for understanding what behaviors the service is expected to produce.
3. **[TestHelper.java](src/main/java/com/example/TestHelper.java)** -- A shared utility placeholder. Check what helpers are (or aren't) available for reuse.
4. **[LegacyTest.java](src/main/java/com/example/LegacyTest.java)** -- A JUnit 4 style test using `TestCase` inheritance. Learn the older testing convention.
5. **[TestNGTest.java](src/main/java/com/example/TestNGTest.java)** -- A TestNG-style test. Compare the annotation syntax against JUnit.
6. **[RogueTestAnnotated.java](src/main/java/com/example/RogueTestAnnotated.java)** -- An intentional anomaly: a `@Test`-annotated class living in `src/main` rather than a test directory.
7. **[ImportOnlyTest.java](src/utils/ImportOnlyTest.java)** and **[UnannotatedInTest.java](src/test/java/com/example/UnannotatedInTest.java)** -- Edge-case classes for exploring static analysis behavior.
8. **[OrderServiceTestStandalone.java](standalone/OrderServiceTest.java)** -- A self-contained test variant outside the `src/` layout.

## Key Entry Points

The codebase is intentionally small. Focus on these files first:

| File | Why it matters |
|------|---------------|
| `src/main/java/com/example/OrderService.java` | The only production class. Understand its API before reading tests. |
| `src/test/java/com/example/OrderServiceTest.java` | The canonical test suite. Shows expected behavior from a consumer perspective. |
| `src/main/java/com/example/TestHelper.java` | The shared utility class (currently a placeholder). |
| `standalone/OrderServiceTest.java` | Shows how the same test looks when removed from standard project layout. |

The remaining files in `src/main/java/com/example/` (`LegacyTest`, `RogueTestAnnotated`, `TestNGTest`) are demonstration code illustrating different testing frameworks and styles.

## Project Structure

```mermaid
flowchart TD
    Main["Main Source<br/>src/main/java/com/example/"]
    Test["Test Source<br/>src/test/java/com/example/"]
    Utils["Utils<br/>src/utils/"]
    Standalone["Standalone<br/>standalone/"]

    Main --> OS["OrderService"]
    Main --> TH["TestHelper"]
    Main --> LT["LegacyTest"]
    Main --> RT["RogueTestAnnotated"]
    Main --> TNG["TestNGTest"]

    Test --> OST["OrderServiceTest"]
    Test --> UIT["UnannotatedInTest"]

    Utils --> IOT["ImportOnlyTest"]

    Standalone --> OSST["OrderServiceTestStandalone"]

    classDef src fill:#e1f5fe,stroke:#01579b
    classDef tst fill:#f3e5f5,stroke:#4a148c
    classDef utl fill:#fff3e0,stroke:#e65100
    class Main,Test,Utils,Standalone src
    class OST,UIT,IOT,OSST tst
    class TH utl
```

### Directory breakdown

- **`src/main/java/com/example/`** -- Core source code. Contains the production `OrderService` class plus a handful of test-related classes placed in main (for demonstration purposes).
- **`src/test/java/com/example/`** -- Standard test source following conventional Maven/Gradle layout. Contains unit tests and a non-annotated comparison class.
- **`src/utils/`** -- Utility source with a lightweight import-only test class.
- **`standalone/`** -- Top-level standalone directory containing a self-contained test variant, demonstrating an alternative project layout.

## Configuration

This project has no external build tool or dependency manager. There is no `pom.xml`, `build.gradle`, or similar configuration file.

- **No build system** -- Compile and run files directly with `javac` and `java`, or import the project into an IDE (IntelliJ, Eclipse) as a plain Java project.
- **No dependency management** -- The project uses no external frameworks beyond the standard Java SE API and the individual test libraries (JUnit 4, JUnit 5, TestNG). If you need to add dependencies, you will need to set up your own build tool.
- **No environment configuration** -- There are no `.properties`, `.yaml`, or `.env` files. The project is self-contained.

## Common Patterns

### Two testing styles, one service

The project demonstrates two distinct patterns for writing tests against `OrderService`:

1. **Annotation-based tests** (`@Test`) -- Used in `OrderServiceTest`, `RogueTestAnnotated`, `TestNGTest`, `ImportOnlyTest`, and the standalone test. This is the modern convention and the one you'll encounter most frequently.
2. **Inheritance-based tests** (`TestCase` subclass) -- Used only in `LegacyTest`. This is the older JUnit 4 approach where test methods must start with `test`.

### Source layout conventions

| Convention | Example |
|-----------|---------|
| Production code lives in `src/main/java/` | `OrderService` |
| Tests live in `src/test/java/` | `OrderServiceTest` |
| Test classes mirror production structure | `com.example.OrderService` -> `com.example.OrderServiceTest` |
| Annotations mark test methods | `@Test` |
| Test helpers are shared via utility classes | `TestHelper` (placeholder) |

### What to avoid

- **Don't put `@Test`-annotated classes in `src/main/`** -- `RogueTestAnnotated` is an intentional anomaly. Production source should contain only production code.
- **Don't assume a class in `src/test/` is a test** -- `UnannotatedInTest` lives in the test directory but has no test annotations. Always check for `@Test` or `extends TestCase`.
- **Don't rely on a build tool** -- There isn't one. If you add one, document it in a new wiki page.

## Next Steps

Once you've read through the files above, consider exploring:

- **[Repository Overview](.codewiki/overview.md)** -- Deeper dive into the technology stack, module guide, and architecture.
- **Running tests** -- Use your IDE's built-in test runner or compile manually with `javac` (adding the JUnit/TestNG jars to the classpath) to see the tests execute.
- **Adding a new test** -- Create a class in `src/test/java/com/example/`, mirror the package of the class under test, and use the `@Test` annotation style shown in `OrderServiceTest`.