# Getting Started

## What This Project Does

`story2-test-code` is a Java-based test harness and reference codebase designed to exercise test discovery, static analysis, and code indexing pipelines. It contains deliberately minimal stubs, placeholder classes, and intentionally imperfect test arrangements (misplaced tests, unused imports, legacy JUnit 3 patterns) that mirror the edge cases real-world Java projects encounter during framework migrations and refactoring. Think of it as a living reference for the kinds of anti-patterns and edge cases that analysis tools should detect and report.

## Recommended Reading Order

If you're new to this codebase, read these wiki pages in order:

1. **[Repository Overview](/.codewiki/overview.md)** -- High-level context, technology stack, and project intent
2. **[Root Module](/.codewiki/root.md)** -- How the three sub-packages relate and the architecture overview
3. **[com.example Module](/.codewiki/com/example.md)** -- The most content-rich page; covers every class with detailed explanations
4. **[Standalone Module](/.codewiki/standalone.md)** -- The minimal isolated test scaffold
5. **[Utils Module](/.codewiki/utils.md)** -- The import-analysis fixture

After the wiki pages, browse the actual source files directly (see the [Project Structure](#project-structure) section below for paths).

## Key Entry Points

Start with these classes to understand the project's intent:

- [`OrderService`](story2-test-code/src/main/java/com/example/OrderService.java) -- The sole production class. It's a no-op stub whose `run()` method is empty. Everything in the project conceptually tests this class.

  ```java
  package com.example;
  public class OrderService { void run() {} }
  ```

- [`RogueTestAnnotated`](story2-test-code/src/main/java/com/example/RogueTestAnnotated.java) -- A JUnit 4 test class (with `@Test`) placed in `src/main/java` instead of `src/test/java`. Demonstrates the "rogue test" anti-pattern that confuses test discovery and coverage tools.

  ```java
  package com.example;
  import org.junit.Test;
  public class RogueTestAnnotated { @Test void test() {} }
  ```

- [`LegacyTest`](story2-test-code/src/main/java/com/example/LegacyTest.java) -- A JUnit 3 test that extends `TestCase` instead of using `@Test` annotations. Represents the pre-annotation testing style encountered during framework migrations.

  ```java
  package com.example;
  import junit.framework.TestCase;
  public class LegacyTest extends TestCase { }
  ```

- [`UnannotatedInTest`](story2-test-code/src/test/java/com/example/UnannotatedInTest.java) -- A class in `src/test/java` with no `@Test` annotation on any method. Exercises the boundary between location-based and annotation-based test identification.

  ```java
  package com.example;
  public class UnannotatedInTest { void run() {} }
  ```

- [`ImportOnlyTest`](story2-test-code/src/utils/ImportOnlyTest.java) -- Imports `org.junit.Test` but never uses it. Serves as a control case for unused-import detection tools.

  ```java
  package utils;
  import org.junit.Test;
  public class ImportOnlyTest { }
  ```

## Project Structure

The project uses the standard Maven directory layout but with intentional irregularities:

```
story2-test-code/
  src/main/java/com/example/    -- Main source: 5 classes
    OrderService.java           -- Production stub (the shared subject under test)
    TestHelper.java             -- Empty placeholder for future test utilities
    LegacyTest.java             -- JUnit 3 legacy test (misplaced in main)
    RogueTestAnnotated.java     -- JUnit 4 test (misplaced in main)
    TestNGTest.java             -- TestNG test (misplaced in main)
  src/test/java/com/example/    -- Test source: 2 classes
    OrderServiceTest.java       -- Properly located JUnit 4 test for OrderService
    UnannotatedInTest.java      -- Test-class sibling without any annotations
  standalone/                    -- Isolated test scaffold: 1 class
    OrderServiceTest.java       -- Standalone JUnit 4 test for OrderService
  src/utils/                     -- Import analysis fixture: 1 class
    ImportOnlyTest.java         -- Unused import placeholder

.codewiki/                       -- Project documentation (wiki)
  overview.md                    -- High-level repository overview
  root.md                        -- Root-level architecture and sub-package guide
  com.md                         -- com package index page
  com/example.md                 -- Detailed class documentation for com.example
  standalone.md                  -- Standalone module documentation
  utils.md                       -- Utils module documentation
```

No other directories or source roots exist. Each class is a single file, typically fewer than 10 lines of code.

## Configuration

This repository does not include build configuration files (no `pom.xml`, `build.gradle`, or similar) -- only source files and documentation. However, the project is structured around standard Maven conventions:

| Convention | How it applies |
|---|---|
| Main source root | `src/main/java` -- production stubs go here |
| Test source root | `src/test/java` -- properly placed tests go here |
| Test discovery | Build tooling (Maven Surefire, Gradle Test) should discover classes annotated with JUnit 4 `@Test` or TestNG `@Test` only within `src/test/java` |
| Test source roots | Classes in `standalone/` and `src/utils/` are non-standard locations; they exercise tooling that scans beyond the conventional source roots |

If you add real build files (Maven or Gradle), ensure the test source roots are correctly configured so that:
- Maven `surefire` discovers JUnit 4 and TestNG tests in `src/test/java`.
- Static analysis tools (PMD, Checkstyle, SpotBugs) flag misplaced tests in `src/main/java` and unused imports.

## Common Patterns

The codebase follows several consistent patterns. Recognizing them will help you navigate and contribute effectively.

### Stub-First Development

Nearly every class is a scaffold with its signature defined but body empty. This allows the build and tooling pipeline to exercise early, before feature implementation begins.

```java
// Stub -- compiles but does no work
public class OrderService { void run() {} }
```

### Intentional Anti-Pattern Inclusion

The `com.example` package deliberately includes common mistakes so that tooling can detect them:

| Anti-pattern | Classes | What it tests |
|---|---|---|
| Tests in `src/main/java` | `RogueTestAnnotated`, `TestNGTest` | Test discovery confusion, coverage skew |
| Legacy JUnit 3 style | `LegacyTest` | Framework migration edge cases |
| Unused imports | `ImportOnlyTest` | Static analysis and import-usage detectors |
| No annotations in test tree | `UnannotatedInTest` | Location-based vs. annotation-based discovery |

These anti-patterns are intentional but temporary -- in a real project, they should be cleaned up.

### Multi-Framework Coexistence

The project uses three testing frameworks side by side, reflecting the fragmentation common during migrations:

| Framework | Import | Classes |
|---|---|---|
| JUnit 3 | `junit.framework.TestCase` | `LegacyTest` |
| JUnit 4 | `org.junit.Test` | `RogueTestAnnotated`, `OrderServiceTest`, `OrderServiceTestStandalone` |
| TestNG | `org.testng.annotations.Test` | `TestNGTest` |

### Empty Classes Need Implementation

`OrderService.run()`, `TestHelper`, `ImportOnlyTest`, and all no-op test methods are scaffolds. When building out real features, these classes need actual logic.

### Naming Conventions

- **Test classes** end with `Test` (e.g., `OrderServiceTest`)
- **Test methods** start with `test` (e.g., `test()`, `run()`)
- **Standalone tests** use a `Standalone` suffix to distinguish them from other variants (e.g., `OrderServiceTestStandalone`)
- **Service/production classes** use a descriptive noun (e.g., `OrderService`)

### No Inter-Class Dependencies

No class in this codebase imports or instantiates another. The only relationships are conceptual -- `OrderServiceTest` is intended to test `OrderService`, and `TestNGTest` parallels `RogueTestAnnotated`. This makes every class independent and easy to scan in isolation.

## What to Do Next

1. Read the **[Repository Overview](/.codewiki/overview.md)** to understand the high-level context.
2. Browse [`com.example`](/.codewiki/com/example.md) to see every class with detailed explanations.
3. Open the source files directly (listed in [Project Structure](#project-structure)) -- each is under 10 lines.
4. When implementing real features, expand the stubs (`OrderService.run()`, `TestHelper`) and move any rogue tests (`RogueTestAnnotated`, `TestNGTest`) to `src/test/java`.