# Getting Started

Welcome to the team. This guide answers "I just joined — where do I start reading?" and points you to the key files and patterns you need to know.

## What This Project Does

This is a small Java project centered around an `OrderService` class and its associated tests. It exercises the service using both JUnit 4 and TestNG to validate different testing conventions — legacy `TestCase` subclasses, annotation-based tests, and standalone test variants.

## Recommended Reading Order

Read the files in this order to build a mental model of the codebase:

1. **[OrderService.java](src/main/java/com/example/OrderService.java)** — the core service class with a single `run()` method. Everything here tests or references it.
2. **[OrderServiceTest.java](src/test/java/com/example/OrderServiceTest.java)** — the primary test class. Shows how `OrderService` is exercised with JUnit.
3. **[TestHelper.java](src/main/java/com/example/TestHelper.java)** — a shared utility class used across tests (currently empty, but the intended home for common test helpers).
4. **[OrderServiceTestStandalone.java](standalone/OrderServiceTest.java)** — an independent test harness runnable outside the standard classpath (e.g. for CI or quick local checks).
5. **[TestNGTest.java](src/main/java/com/example/TestNGTest.java)** and **[RogueTestAnnotated.java](src/main/java/com/example/RogueTestAnnotated.java)** — explore these if you need to understand how TestNG and annotation-based tests are used, or why some test-like files live in `src/main`.

## Key Entry Points

| Class | Location | Why it matters |
|---|---|---|
| `OrderService` | `src/main/java/com/example/OrderService.java` | Core application class — the service under test. Start here. |
| `OrderServiceTest` | `src/test/java/com/example/OrderServiceTest.java` | Primary test class using JUnit `@Test`. Shows expected behavior. |
| `TestHelper` | `src/main/java/com/example/TestHelper.java` | Shared test utility. Currently empty but the intended home for common helpers. |

## Project Structure

The project follows a standard Java layout with some unusual additions — test-like files live in `src/main` and a `standalone/` directory exists outside the standard Maven/Gradle tree.

```mermaid
flowchart TD
    subgraph main["src/main/java/com/example/ - Main Source"]
        OS["OrderService"]
        TH["TestHelper"]
    end
    subgraph tests["src/test/java/com/example/ - Test Code"]
        OST["OrderServiceTest"]
        UIT["UnannotatedInTest"]
    end
    subgraph standalone["standalone/ - Standalone Tests"]
        OSTS["OrderServiceTestStandalone"]
    end
    OST --> OS
    OSTS --> OS
```

### Directory breakdown

- **`src/main/java/com/example/`** — application source code. Contains `OrderService` and a few test-like stubs (`LegacyTest`, `RogueTestAnnotated`, `TestNGTest`) that should likely be moved.
- **`src/test/java/com/example/`** — standard test directory. `OrderServiceTest` is the primary test class.
- **`src/utils/`** — utility code (`ImportOnlyTest.java`). Imports JUnit's `@Test` but contains no test methods — likely a placeholder.
- **`standalone/`** — independent test file (`OrderServiceTestStandalone.java`) that can run without the standard build classpath.

## Configuration

The repository does not include a `pom.xml`, `build.gradle`, or `settings.yml` at the root. The project relies on the standard Java source layout (`src/main`, `src/test`) and should be built with a standard Java toolchain.

Key build expectations:

- **Java**: any recent LTS release (the code uses JUnit 4 and TestNG, so Java 8+ is safe).
- **Dependencies**: JUnit 4 (`org.junit.Test`), TestNG (`org.testng.annotations.Test`). No application-level frameworks are detected.
- **Tests**: Both JUnit and TestNG tests should be able to run — check your build tool's configuration for dual-framework support.

## Common Patterns

### Testing conventions

- **JUnit 4 style**: Classes in `src/test` use `@Test` from `org.junit.Test` (e.g., `OrderServiceTest.java`).
- **TestNG style**: `TestNGTest.java` uses `@Test` from `org.testng.annotations.Test`.
- **Legacy pattern**: `LegacyTest.java` extends `junit.framework.TestCase` (JUnit 3 style). This is an old pattern — prefer `@Test` annotations going forward.
- **Stub files**: Several files (`TestHelper`, `LegacyTest`, `UnannotatedInTest`, `ImportOnlyTest`) appear to be no-op stubs or placeholders. Skim them but don't expect production logic.

### Code patterns

- **Minimal service**: `OrderService` has a single `run()` method. The class follows a simple one-class-one-concern approach.
- **Annotation-based tests**: Both JUnit and TestNG tests use the `@Test` annotation rather than inheriting from a base class.
- **Empty placeholders**: `TestHelper` and `UnannotatedInTest` are empty or contain no-op methods. They may be waiting to be filled in or removed.

### Files to be aware of

| File | Note |
|---|---|
| `RogueTestAnnotated.java` | Has `@Test` but lives in `src/main` — unusual. Consider moving to `src/test`. |
| `TestNGTest.java` | Test-style class in `src/main` — should likely be under `src/test`. |
| `ImportOnlyTest.java` | Imports `@Test` but has no test methods. Placeholder. |
| `LegacyTest.java` | JUnit 3 `TestCase` pattern. Legacy stub. |

## Next Steps

After reading through the files above:

1. Run the tests against your local Java installation to verify the setup works.
2. Read the **[Repository Overview](../overview.md)** for a deeper architecture diagram and module-by-module guide.
3. Look into how `OrderService` should be extended or tested if you have a task assigned.