# Com / Example

The `com.example` package is a demonstration set of Java classes that illustrates common test-related patterns, anti-patterns, and edge cases encountered during project setup. It contains a mix of production stubs, JUnit 3 and JUnit 4 style tests, a TestNG test, and placeholder classes — all intentionally kept minimal. This package appears to serve as a reference or test harness for tooling validation rather than production functionality.

## Overview

This module is organized across the standard Maven directory layout but with intentional irregularities designed to exercise test discovery and indexing tools:

- **`src/main/java/com/example/`** — contains five classes that include a service stub, legacy and annotated test classes living outside the test source set, and an empty helper.
- **`src/test/java/com/example/`** — contains two test-related classes, one annotated with JUnit's `@Test` and one with no test annotations at all.

The package is a **subpackage** at the root level and has no child submodules, imports, or cross-module dependencies.

## Key Classes and Interfaces

### LegacyTest — JUnit 3 TestCase Stub

**Source:** [`LegacyTest.java`](story2-test-code/src/main/java/com/example/LegacyTest.java)

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

`LegacyTest` extends JUnit 3's `junit.framework.TestCase`. It is a bare subclass with no test methods, serving as a placeholder for a legacy test style. Notably, it lives in `src/main/java` rather than the conventional `src/test/java`, which makes it a candidate for misclassification by tooling that indexes test code based solely on location.

**Why it matters:** JUnit 3 tests use `extends TestCase` instead of annotation-based discovery (`@Test`). Modern tooling often needs to handle both styles, and this class provides a minimal example of the older pattern.

**Key details:**
- No methods defined beyond those inherited from `TestCase`.
- No constructor overrides.

### OrderService — Service Stub

**Source:** [`OrderService.java`](story2-test-code/src/main/java/com/example/OrderService.java)

```java
public class OrderService {
    void run() {}
}
```

`OrderService` is a minimal production class representing an order-handling service. Its sole method, `run()`, is a no-op (empty body, `void` return type).

**Key details:**
- `run()` — performs no operation. Takes no parameters and returns nothing.
- This appears to be a stub placeholder intended to be replaced with actual order-processing logic during implementation.

**Relationship to tests:** This class is the subject of `OrderServiceTest` in the test source tree, though the test method is itself a no-op stub.

### RogueTestAnnotated — Annotated Test in Main Source

**Source:** [`RogueTestAnnotated.java`](story2-test-code/src/main/java/com/example/RogueTestAnnotated.java)

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

`RogueTestAnnotated` carries JUnit 4's `@Test` annotation but is **defined in `src/main/java`** instead of `src/test/java`. This is an anti-pattern — a "rogue" test class accidentally left in the main source set. The `test()` method itself is a no-op.

**Why it matters:** Test discovery tooling, build configurations, and static analysis often assume all `@Test`-annotated classes live under `src/test/java`. A rogue class in main can cause:
- Tests to run in the application classpath rather than the test classpath.
- Build tool miscounting or misreporting test coverage.
- Integration tests inadvertently becoming part of the production artifact.

**Key details:**
- `test()` — no-op method annotated with `@org.junit.Test`.
- Depends on JUnit 4 (`import org.junit.Test`).

### TestHelper — Empty Placeholder

**Source:** [`TestHelper.java`](story2-test-code/src/main/java/com/example/TestHelper.java)

```java
public class TestHelper { }
```

`TestHelper` is an empty class with no fields, methods, or constructors. It serves as a stub or scaffold — likely intended to be populated with shared test utility methods in the future but currently a no-op.

**Key details:**
- No methods defined.
- No dependencies.

### TestNGTest — TestNG Test in Main Source

**Source:** [`TestNGTest.java`](story2-test-code/src/main/java/com/example/TestNGTest.java)

```java
import org.testng.annotations.Test;
public class TestNGTest {
    @Test void run() {}
}
```

`TestNGTest` uses the TestNG testing framework's `@Test` annotation and is also placed in `src/main/java`. Like `RogueTestAnnotated`, this is an anti-pattern — a test class from an alternative test framework living outside the test source tree.

**Key details:**
- `run()` — no-op method annotated with `@org.testng.annotations.Test`.
- Depends on TestNG (`import org.testng.annotations.Test`).
- Illustrates the same misplacement concern as `RogueTestAnnotated`, but with a different framework annotation.

### OrderServiceTest — JUnit Test for OrderService

**Source:** [`OrderServiceTest.java`](story2-test-code/src/test/java/com/example/OrderServiceTest.java)

```java
import org.junit.Test;
public class OrderServiceTest {
    @Test void test() {}
}
```

`OrderServiceTest` is a properly located JUnit 4 test class in `src/test/java`. Its single `test()` method is annotated with `@Test` but contains no assertions or actual test logic — it is a stub.

**Key details:**
- `test()` — no-op method. Intended to test `OrderService` in the future.
- Depends on JUnit 4 (`import org.junit.Test`).

### UnannotatedInTest — Test Class Without Annotations

**Source:** [`UnannotatedInTest.java`](story2-test-code/src/test/java/com/example/UnannotatedInTest.java)

```java
public class UnannotatedInTest {
    void run() {}
}
```

`UnannotatedInTest` lives in the test source tree but has no `@Test` annotation on any of its methods. It defines a single `run()` method with no test marker.

**Why it matters:** This class exercises the edge case where a file in `src/test/java` is not actually a test from the framework's perspective. Tooling that relies solely on file location will assume it is a test, but annotation-based discoverers will skip it. This can cause discrepancies between file counts and discovered test counts.

**Key details:**
- `run()` — no-op method with no annotations.
- No framework dependencies imported.

## How It Works

This package does not implement any production workflow or request-handling flow. Instead, it is structured to demonstrate several test-related scenarios:

1. **Multiple test frameworks coexisting** — JUnit 3 (`TestCase`), JUnit 4 (`@Test` from `org.junit.Test`), and TestNG (`@Test` from `org.testng.annotations.Test`) are all represented, illustrating the fragmentation often seen in Java projects during framework migration.

2. **Main-source test anti-patterns** — `RogueTestAnnotated` and `TestNGTest` are test classes that reside in `src/main/java`. Any automated process that scans `src/main/java` for test methods will find them, potentially skewing metrics.

3. **Test discovery edge cases** — `UnannotatedInTest` in `src/test/java` with no annotations tests the boundary between location-based and annotation-based test identification.

4. **Production stubs** — `OrderService` and `TestHelper` are empty scaffolds, showing how production code often begins as placeholders before feature implementation.

## Data Model

This module does not define any data model classes, DTOs, entity objects, or configuration structures. All classes are behavioral stubs with no state (no fields, no constructors with parameters).

## Dependencies and Integration

This module has **no package dependencies** and **no cross-module relationships** detected. It imports from external test frameworks:

| Import | From |
|---|---|
| `junit.framework.TestCase` | JUnit 3 |
| `org.junit.Test` | JUnit 4 |
| `org.testng.annotations.Test` | TestNG |

There are no inter-class references — none of the classes in this module instantiate or depend on each other. The only logical relationships are conceptual: `OrderServiceTest` is intended to test `OrderService`, and `TestNGTest` conceptually parallels `RogueTestAnnotated` as a TestNG-style counterpart.

```mermaid
flowchart LR
    subgraph MAIN["src/main/java/com/example"]
        LT["LegacyTest
JUnit 3 TestCase"]
        OS["OrderService
Service stub"]
        RTA["RogueTestAnnotated
JUnit @Test in main"]
        TH["TestHelper
Empty placeholder"]
        TNG["TestNGTest
TestNG @Test in main"]
    end
    subgraph TEST["src/test/java/com/example"]
        OST["OrderServiceTest
JUnit @Test in test"]
        UIT["UnannotatedInTest
No annotations"]
    end
    LT --- OS
    RTA --- OS
    OST --- OS
    TNG --- RTA
```

The diagram above shows the logical relationships: `OrderService` is the shared production target referenced by both the rogue test (`RogueTestAnnotated`) and the proper test (`OrderServiceTest`).

## Notes for Developers

- **This is a demonstration package.** The classes are intentionally minimal. Do not treat them as a template for production code.
- **Rogue tests should be removed.** If `RogueTestAnnotated` or `TestNGTest` are genuine tests, they should be moved to `src/test/java`. If they are not tests, remove their framework annotations.
- **JUnit 3 is legacy.** `LegacyTest` uses the deprecated `extends TestCase` pattern. Any JUnit 3-style test classes should be migrated to annotation-based JUnit 4/5 style.
- **Empty classes are scaffolds.** `TestHelper` and `OrderService.run()` are placeholders. If you are implementing features in this area, expand these classes with actual logic.
- **Build tool awareness.** If you add real test methods, ensure your build configuration (Maven `surefire` / Gradle `test`) correctly discovers JUnit 4 and TestNG annotations, and that the test source root is properly configured.