# Story2testcode

## Overview

The `story2testcode` module is a synthetic test-code package designed to exercise and validate the **story-to-test-code tooling pipeline** rather than implement real business logic. It is part of a broader migration effort (Story 2) to standardize and modernize how tests are organized, detected, and generated across the codebase.

At its core, this module serves two purposes:

1. **Tool validation** — It provides deliberately minimal, intentionally varied stub classes scattered across different source directories (`src/main/java`, `src/test/java`, `src/utils`, `standalone/`) and written against multiple test frameworks (JUnit 3, JUnit 4, TestNG). These fixtures ensure the tooling pipeline correctly classifies test classes, distinguishes framework annotations, handles non-standard source layouts, and avoids false positives on non-test classes.

2. **Shared test infrastructure** — Through its `Helpers` subpackage, the module is building a foundation for reusable test utilities. The `TestHelper` class (currently a placeholder) is intended to become the single source of common test utilities — builders, assertions, and fixture generators — that multiple test suites can share, reducing duplication across JUnit, TestNG, and legacy test frameworks.

The module sits at the root of the project hierarchy and contains no child modules of its own. Its 9 indexed source files are organized into three logical groupings that work together as a system: helpers (shared utilities), services (the target under test), and other (the fixture stubs that validate tool behavior).

## Sub-module Guide

### Helpers — Shared Test Utilities

The `Helpers` package is the shared utilities layer. Its sole class, `TestHelper`, is currently an empty placeholder with no methods or fields. Its role is defined by its intended future use: to consolidate common test utilities — object builders, assertion helpers, fixture data generators — so that multiple test classes can share the same base logic rather than each redefining their own.

`TestHelper` is designed to be the companion to `OrderService` (from the `Services` package). When test utilities are added, they should be `public static` methods that operate independently, making them easy to call from any test regardless of framework.

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

### Services — Service Under Test

The `Services` package contains `OrderService`, a single-method scaffold with an empty `run()` method. This class appears to be the **target under test** — the service whose behavior future test utilities in `TestHelper` would exercise. It is a sibling to the test fixtures in the `Other` package.

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

### Other — Fixture Stubs for Tool Validation

The `Other` package is the largest and most nuanced grouping. It contains seven intentionally minimal classes that serve as **synthetic test targets** for the story-to-test-code tooling pipeline. Each one exercises a distinct detection or classification path:

| Class | Location | Purpose |
|---|---|---|
| `LegacyTest` | `src/main/java` | Exercises JUnit 3 `TestCase` inheritance detection |
| `RogueTestAnnotated` | `src/main/java` | Tests `@Test` annotation detection in the main source tree |
| `TestNGTest` | `src/main/java` | Validates TestNG annotation recognition (not confused with JUnit) |
| `OrderServiceTest` | `src/test/java` | Baseline "happy path" — standard JUnit 4 test in the conventional location |
| `UnannotatedInTest` | `src/test/java` | Ensures classes in the test directory without `@Test` annotations are not misclassified as tests |
| `ImportOnlyTest` | `src/utils/` | Tests handling of orphaned imports — imports `@Test` but never uses it |
| `OrderServiceTestStandalone` | `standalone/` | Tests test detection in non-standard, custom source directories |

These classes are **intentionally independent** — no class imports or references another. Each is self-contained and minimal (no fields, no constructors beyond the implicit default). Together they form a comprehensive test suite for the tool's classification logic.

**Source files:** [`LegacyTest.java`](story2-test-code/src/main/java/com/example/LegacyTest.java), [`RogueTestAnnotated.java`](story2-test-code/src/main/java/com/example/RogueTestAnnotated.java), [`TestNGTest.java`](story2-test-code/src/main/java/com/example/TestNGTest.java), [`OrderServiceTest.java`](story2-test-code/src/test/java/com/example/OrderServiceTest.java), [`UnannotatedInTest.java`](story2-test-code/src/test/java/com/example/UnannotatedInTest.java), [`ImportOnlyTest.java`](story2-test-code/src/utils/ImportOnlyTest.java), [`OrderServiceTest.java`](story2-test-code/standalone/OrderServiceTest.java)

## How the Sub-modules Work Together

These three sub-packages form a cohesive system for testing and validating the story-to-test-code pipeline:

```mermaid
flowchart TD
    subgraph story2testcode["story2testcode module"]
        subgraph helpers["Helpers Package"]
            TH["TestHelper
(empty placeholder)"]
        end
        subgraph services["Services Package"]
            OS["OrderService
(scaffold)"]
        end
        subgraph other["Other Package
(fixture stubs)"]
            LT["LegacyTest
JUnit 3"]
            RT["RogueTestAnnotated
JUnit 4"]
            TN["TestNGTest
TestNG"]
            OST["OrderServiceTest
standard JUnit 4"]
            UIT["UnannotatedInTest
no annotation"]
            IOT["ImportOnlyTest
unused import"]
            OSST["OrderServiceTestStandalone
non-standard dir"]
        end
    end

    TH -.->|"intended to support"| OST
    TH -.->|"intended to support"| OS
    OST -.->|"tests"| OS
    LT -.->|"extends TestCase"| J3["junit.framework.TestCase"]
    RT -.->|"imports @Test"| J4["org.junit.Test"]
    TN -.->|"imports @Test"| TNG["org.testng.annotations.Test"]
    OST -.->|"imports @Test"| J4
    OSST -.->|"imports @Test"| J4
    IOT -.->|"imports (unused)"| J4
    UIT -.->|"no imports"| NONE["none"]
```

The relationships between these sub-packages form a layered testing strategy:

- **Helpers feeds Services** — `TestHelper` is intended to eventually provide shared utilities that make testing `OrderService` easier and more consistent.
- **Other tests Other** — The fixture stubs in `Other` exist primarily to validate that the tooling pipeline correctly classifies them. `OrderServiceTest` in this package additionally serves as the baseline "happy path" fixture.
- **Services is the target** — `OrderService` sits in the middle as the code under test. It is the production-side artifact, while `Other` contains the test-side artifacts that verify its behavior (when they eventually contain real assertions).

## Key Patterns and Architecture

### Multi-Framework Detection

The module spans three test frameworks to validate that the tooling pipeline correctly distinguishes between them. This is a critical architectural concern because JUnit 3 (`junit.framework.TestCase` inheritance), JUnit 4/5 (`@Test` annotation on methods), and TestNG (`org.testng.annotations.Test`) all represent test classes but follow fundamentally different detection paths:

- **Inheritance-based detection** — `LegacyTest` uses JUnit 3's pattern of extending `TestCase`. The tool must recognize that subclasses of `TestCase` with `testXxx` method naming conventions are test classes, even without annotations.

- **Annotation-based detection** — `RogueTestAnnotated` and `TestNGTest` both use method-level annotations, but from different packages. The tool must distinguish `org.junit.Test` from `org.testng.annotations.Test` rather than treating them identically.

- **Convention vs. annotation** — The module tests both approaches to ensure the tool handles the full spectrum of test detection strategies.

### Source Location Flexibility

Tests are deliberately scattered across four different source directories:

| Directory | Classes | Edge Case |
|---|---|---|
| `src/main/java` | `LegacyTest`, `RogueTestAnnotated`, `TestNGTest` | Test code in the main source tree ("rogue" tests) |
| `src/test/java` | `OrderServiceTest`, `UnannotatedInTest` | Conventional test location |
| `src/utils` | `ImportOnlyTest` | Non-standard utility source directory |
| `standalone/` | `OrderServiceTestStandalone` | Root-level custom source directory |

This ensures the tool does not hardcode expected source directories but instead relies on actual code analysis (annotation presence, inheritance checks) to identify test classes.

### False Positive Rejection

Two classes (`UnannotatedInTest` and `ImportOnlyTest`) are specifically designed to ensure the tool does not misclassify non-test classes:

- **Unannotated in test directory** — `UnannotatedInTest` lives in `src/test/java` but has no `@Test` annotations on its methods. Naive test discovery that only checks file location would incorrectly classify this as a test class.
- **Orphaned imports** — `ImportOnlyTest` imports `org.junit.Test` but never uses it in any method. Tooling that checks for import presence without verifying actual usage would produce a false positive here.

### Placeholder Pattern

Both `TestHelper` (in `Helpers`) and `OrderService` (in `Services`) follow a **placeholder/scaffold pattern** — they exist as structural foundations for future implementation. `TestHelper` is intended to grow into a rich utility class; `OrderService` is intended to become a real service with business logic. This is consistent with the module's role as a migration target: the structure is being established now, and the implementation will follow.

## Dependencies and Integration

### External Dependencies

The module depends on three external test framework libraries, each used by specific fixture classes:

| Dependency | Used By | Purpose |
|---|---|---|
| `junit.framework.TestCase` | `LegacyTest` | JUnit 3 inheritance-based test detection |
| `org.junit.Test` | `RogueTestAnnotated`, `OrderServiceTest`, `ImportOnlyTest`, `OrderServiceTestStandalone` | JUnit 4 annotation-based test detection |
| `org.testng.annotations.Test` | `TestNGTest` | TestNG annotation-based test detection |

### Internal Module Dependencies

There are no internal module dependencies — no class imports or references another class within the `story2testcode` module. All classes are self-contained stubs. The relationships between sub-packages are **conceptual and intended** rather than coded:

- `TestHelper` intends to provide utilities for `OrderService` testing (but currently has no methods to call).
- `OrderServiceTest` in the `Other` package is named to suggest it tests `OrderService`, but it is a standalone stub with no actual imports of `OrderService`.

### Cross-Module Relationships

No cross-module relationships were detected in the index. This module exists as a standalone unit within the broader project, serving as a test-bed for the story-to-test-code tooling pipeline rather than a production dependency of other modules.

## Notes for Developers

### Working with Helpers

- `TestHelper` is currently empty by design. It is an intentional extension point for shared test utility methods.
- When adding helpers, prefer `public static` methods with no side effects to keep them easy to invoke from any test framework.
- Any new helpers should be **framework-agnostic** or provide separate variants per framework (JUnit 3, JUnit 4, TestNG), since the parent package contains tests written against all three.
- Helpers should be designed to assist with `OrderService` testing — for example, builders for order fixtures or common assertions on order state.

### Working with Services

- `OrderService` is a stub. The `run()` method exists but contains no implementation logic.
- When extending this service, consider adding concrete order processing behavior and wiring it to relevant data models or repositories.
- As the target under test for the module's test fixtures, the service's API should remain stable to avoid breaking test detection validation.

### Working with Other

- **Do not refactor to add behavior.** These classes are intentionally empty stubs. Adding assertions, test methods, or state to them would break the fixtures that exercise the tool's detection logic.
- **Location matters.** Each class is deliberately placed in a different source directory to test the tool's source tree handling. Changing a class's file path should be done with awareness of which edge case it covers.
- **Annotation vs. inheritance distinction.** When working on test detection logic, be careful not to conflate JUnit 3 `TestCase` inheritance with JUnit 4/5 annotation-based detection — they follow different code paths and must be handled separately.
- **The `ImportOnlyTest` edge case is subtle.** It imports `org.junit.Test` but never uses it. Tooling that checks for import presence without verifying actual usage will produce a false positive here.
- **The `UnannotatedInTest` edge case is equally subtle.** A class in the test directory with a method named `run()` (not `testXxx`) and no annotations is not a test, despite its file location. The tool must distinguish between "file in test dir" and "file that is actually a test."

### Module Structure

- The module contains 9 source files across 4 different source directories.
- There are no child wiki pages or child modules — all structure is within the top-level package.
- No class-level symbols, method-level symbols, or package dependencies were detected in the index, confirming the stub nature of the codebase.
- The module appears to be an example/test project (`story2-test-code`) rather than production code, consistent with its role in validating test code generation tooling.