ga-plugins-cli 0.1.0 → 0.1.2

package/plugins/migration-safety/commands/gen-characterization-test.md

@@ -0,0 +1,452 @@
+# Command: gen-characterization-test
+
+Generate characterization test scaffolding that captures the behavioral contract of the OLD Java service, so that the new Go service can be validated against it. This command produces test scaffolding — a human must run the Java service to capture actual golden data.
+
+---
+
+## Step 1: Identify the Service
+
+Ask the user:
+
+> "What is the name or path of the Java service you want to characterize?
+> (e.g., `services/booking-java-svc` or just `booking-svc`)"
+
+Record as `<service-name>` and `<service-path>`.
+
+If a path was given, check that the directory exists and contains Java source files. If not, inform the user and ask to clarify.
+
+---
+
+## Step 2: Choose the Test Format
+
+Present the following options to the user:
+
+> "Choose a characterization test format:
+>
+> **Option A — Golden JSON files** (recommended default)
+>   Simple. No extra tooling. Capture request/response pairs as JSON fixtures.
+>   Good for: small teams, early migration phase, services with stable contracts.
+>   Requires: manually running the Java service and saving HTTP responses as `.json` files.
+>
+> **Option B — Pact consumer-driven contracts**
+>   Stronger cross-team contracts. Versioned. Detectable breaking changes.
+>   Requires: a running Pact broker (e.g., PactFlow), Pact Go library.
+>   Good for: services consumed by multiple teams, long migration timelines.
+>
+> **Option C — HTTP recording (VCR-style)**
+>   Record real traffic against the Java service, replay against the Go service.
+>   Requires: HTTP recording library (e.g., `dnaeon/go-vcr`), Java service running during recording.
+>   Good for: services with complex request/response sequences.
+>
+> **NEEDS DECISION** — choose A, B, or C. If you proceed without choosing, Option A (golden JSON) will be used as the default."
+
+If the user does not choose, default to Option A and note this in the generated output.
+
+Record the choice as `<test-format>`.
+
+---
+
+## Step 3: Identify Endpoints to Cover
+
+Ask the user:
+
+> "Which endpoints should be covered by characterization tests?
+> You can say 'all' to cover every endpoint, or list specific ones (e.g., `POST /api/v1/bookings`, `GET /api/v1/bookings/{id}`)."
+
+If the user says "all" and a path was provided, scan the Java source for `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`, `@RequestMapping` annotations and list all found endpoints. Show the list to the user and confirm.
+
+Record as `<endpoint-list>`.
+
+---
+
+## Step 4: Identify the Corresponding Go Service
+
+Ask the user:
+
+> "What is the path to the new Go service draft that these tests will validate against?
+> (e.g., `flight-ops-svc/draft-booking-java-svc/` or the final merged service path)"
+
+Record as `<go-service-path>`.
+
+---
+
+## Step 5: Generate Scaffolding Based on Format
+
+### Format A: Golden JSON Files
+
+Create the following structure:
+
+```
+<go-service-path>/
+  testdata/
+    golden/
+      README.md                        # instructions for capturing golden data
+      <endpoint-slug>/
+        <scenario-name>_request.json   # HTTP request body fixture
+        <scenario-name>_response.json  # PLACEHOLDER — must be filled by human
+  characterization_test.go             # Go test loading fixtures and comparing responses
+```
+
+#### testdata/golden/README.md
+
+Write:
+
+```markdown
+# Golden Data Capture Instructions
+
+These JSON files capture the known-good behavior of the Java service: `<service-name>`.
+They are used by `characterization_test.go` to verify the Go service produces equivalent responses.
+
+## How to Capture Golden Data
+
+1. Start the Java service locally or in a test environment:
+   ```
+   cd <service-path>
+   mvn spring-boot:run
+   # or: java -jar target/<service-name>.jar
+   ```
+   The service should be running on its default port (check application.properties).
+
+2. For each `*_request.json` file in this directory, send the request to the Java service:
+   ```
+   curl -s -X <METHOD> http://localhost:<PORT><PATH> \
+     -H "Content-Type: application/json" \
+     -d @<endpoint-slug>/<scenario>_request.json \
+     > <endpoint-slug>/<scenario>_response.json
+   ```
+
+3. Capture the HTTP status code separately:
+   ```
+   curl -s -o /dev/null -w "%{http_code}" -X <METHOD> http://localhost:<PORT><PATH> \
+     -H "Content-Type: application/json" \
+     -d @<endpoint-slug>/<scenario>_request.json
+   ```
+   Update the `expectedStatus` field in `characterization_test.go` for each scenario.
+
+4. Repeat for error scenarios (invalid input, not-found IDs, unauthorized requests).
+
+5. Once all `*_response.json` files are populated, remove the `t.Skip()` calls from `characterization_test.go`.
+
+## Important Notes
+
+- Capture responses from the Java service BEFORE switching any traffic to Go.
+- If the Java service uses a database, seed the same test data before each capture run.
+- Store the DB seed script in `testdata/sql/seed.sql`.
+- Do NOT commit real customer data as golden fixtures — use synthetic test data only.
+```
+
+#### characterization_test.go
+
+Write:
+
+```go
+// AUTO-GENERATED CHARACTERIZATION TEST SCAFFOLDING
+// Purpose: verify Go service <go-service-path> produces equivalent responses to Java <service-name>
+// Format: Golden JSON (Option A)
+//
+// BEFORE RUNNING:
+//   1. Read testdata/golden/README.md
+//   2. Capture golden data from the running Java service
+//   3. Remove t.Skip() calls for populated fixtures
+//
+// Run: go test -v ./... -run Characterization
+
+package characterization_test
+
+import (
+    "encoding/json"
+    "net/http"
+    "net/http/httptest"
+    "os"
+    "path/filepath"
+    "testing"
+
+    "github.com/go-chi/chi/v5"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+// goldenDir is the root of the golden fixture directory.
+const goldenDir = "testdata/golden"
+
+// CharacterizationScenario describes one request/response fixture pair.
+type CharacterizationScenario struct {
+    Name           string
+    Method         string
+    Path           string
+    RequestFile    string // relative to goldenDir
+    ResponseFile   string // relative to goldenDir — PLACEHOLDER until captured from Java
+    ExpectedStatus int    // update after capturing from Java service
+}
+
+// scenarios lists every endpoint and scenario to characterize.
+// TODO(human): populate ExpectedStatus for each scenario after running Java service.
+// TODO(human): add additional scenarios (error cases, edge cases) as you discover them.
+var scenarios = []CharacterizationScenario{
+    // Generated from endpoint list: <endpoint-list>
+    {
+        Name:           "create booking - valid request",
+        Method:         http.MethodPost,
+        Path:           "/api/v1/bookings",
+        RequestFile:    "create_booking/valid_request.json",
+        ResponseFile:   "create_booking/valid_response.json",
+        ExpectedStatus: 201, // TODO(human): verify against actual Java response
+    },
+    {
+        Name:           "create booking - invalid body",
+        Method:         http.MethodPost,
+        Path:           "/api/v1/bookings",
+        RequestFile:    "create_booking/invalid_body_request.json",
+        ResponseFile:   "create_booking/invalid_body_response.json",
+        ExpectedStatus: 400, // TODO(human): verify against actual Java response
+    },
+    // TODO(human): add one scenario per endpoint in <endpoint-list>
+}
+
+func TestCharacterization_GoldenJSON(t *testing.T) {
+    t.Skip("NEEDS GOLDEN DATA: read testdata/golden/README.md, run Java service, capture responses. Remove this Skip when all *_response.json files are populated.")
+
+    // TODO(human): initialize Go service router here
+    // Example:
+    //   cfg, _ := config.Load()
+    //   db, _ := database.New(cfg.DatabaseURL)
+    //   ... wire dependencies ...
+    //   r := chi.NewRouter()
+    //   handler.NewBookingHandler(bookingUC).RegisterRoutes(r)
+    var r chi.Router // replace with your real router initialization
+    _ = r
+
+    server := httptest.NewServer(r)
+    defer server.Close()
+
+    for _, sc := range scenarios {
+        t.Run(sc.Name, func(t *testing.T) {
+            // Load request fixture
+            reqPath := filepath.Join(goldenDir, sc.RequestFile)
+            reqBody, err := os.ReadFile(reqPath)
+            require.NoError(t, err, "request fixture must exist: %s — create it if missing", reqPath)
+
+            // Send request to Go service
+            req, err := http.NewRequest(sc.Method, server.URL+sc.Path, bytesReader(reqBody))
+            require.NoError(t, err)
+            req.Header.Set("Content-Type", "application/json")
+
+            resp, err := http.DefaultClient.Do(req)
+            require.NoError(t, err)
+            defer resp.Body.Close()
+
+            // Check status code
+            assert.Equal(t, sc.ExpectedStatus, resp.StatusCode,
+                "HTTP status mismatch for %s %s", sc.Method, sc.Path)
+
+            // Load response fixture
+            respPath := filepath.Join(goldenDir, sc.ResponseFile)
+            goldenBody, err := os.ReadFile(respPath)
+            require.NoError(t, err,
+                "response fixture must exist: %s — capture from Java service first", respPath)
+
+            // Compare response bodies (JSON-normalized)
+            var golden, actual interface{}
+            require.NoError(t, json.Unmarshal(goldenBody, &golden))
+            require.NoError(t, json.NewDecoder(resp.Body).Decode(&actual))
+            assert.Equal(t, golden, actual,
+                "response body mismatch for %s %s — Go response differs from Java golden", sc.Method, sc.Path)
+        })
+    }
+}
+
+func bytesReader(b []byte) *bytes.Reader {
+    return bytes.NewReader(b)
+}
+```
+
+Also create placeholder request fixture files. For each endpoint, write a minimal `*_request.json` placeholder:
+
+```json
+{
+  "_PLACEHOLDER": true,
+  "_instructions": "Replace this file with a real request body for the Java service endpoint.",
+  "_endpoint": "<METHOD> <PATH>"
+}
+```
+
+And a minimal `*_response.json` placeholder:
+
+```json
+{
+  "_PLACEHOLDER": true,
+  "_instructions": "Run the Java service and capture the real response here. See testdata/golden/README.md.",
+  "_endpoint": "<METHOD> <PATH>"
+}
+```
+
+---
+
+### Format B: Pact Consumer-Driven Contracts
+
+Create:
+
+```
+<go-service-path>/
+  contract/
+    pact/
+      <service-name>_pact_test.go    # Pact consumer test skeleton
+      README.md                       # Pact setup instructions
+```
+
+Write `<service-name>_pact_test.go`:
+
+```go
+// AUTO-GENERATED PACT CONTRACT TEST SCAFFOLDING
+// Format: Pact consumer-driven contracts (Option B)
+//
+// BEFORE RUNNING:
+//   1. Install Pact Go: go get github.com/pact-foundation/pact-go/v2
+//   2. Set up a Pact broker (PactFlow or self-hosted)
+//   3. Set PACT_BROKER_URL, PACT_BROKER_TOKEN environment variables
+//   4. Fill in interaction expectations below based on actual Java service behavior
+//
+// Run: go test -v ./contract/pact/...
+
+package pact_test
+
+import (
+    "fmt"
+    "testing"
+
+    "github.com/pact-foundation/pact-go/v2/consumer"
+    "github.com/pact-foundation/pact-go/v2/matchers"
+    "github.com/stretchr/testify/require"
+)
+
+func TestPact_<ServiceName>_CreateBooking(t *testing.T) {
+    t.Skip("NEEDS SETUP: configure Pact broker and fill in interaction expectations from Java service behavior")
+
+    mockProvider, err := consumer.NewV2Pact(consumer.MockHTTPProviderConfig{
+        Consumer: "go-<go-service-name>",
+        Provider: "java-<service-name>",
+    })
+    require.NoError(t, err)
+
+    // TODO(human): define interactions based on observed Java service behavior
+    err = mockProvider.
+        AddInteraction().
+        Given("a valid booking request").
+        UponReceiving("a POST /api/v1/bookings request").
+        WithRequest("POST", "/api/v1/bookings").
+        WithHeader("Content-Type", matchers.S("application/json")).
+        WithBody(matchers.MapMatcher{
+            "flightId":    matchers.S("FL-001"),
+            "seatCount":   matchers.Integer(2),
+            "passengerId": matchers.S("P-001"),
+        }).
+        WillRespondWith(201).
+        WithHeader("Content-Type", matchers.S("application/json")).
+        WithBody(matchers.MapMatcher{
+            "id":     matchers.Regex("BK-[0-9]+", "BK-001"),
+            "status": matchers.S("PENDING"),
+        }).
+        ExecuteTest(t, func(config consumer.MockServerConfig) error {
+            // TODO(human): call your Go service client against config.Host:config.Port
+            return fmt.Errorf("implement me: call Go client against mock provider")
+        })
+
+    require.NoError(t, err)
+}
+```
+
+---
+
+### Format C: HTTP Recording (VCR-Style)
+
+Create:
+
+```
+<go-service-path>/
+  testdata/
+    cassettes/                       # VCR cassette files (recorded HTTP interactions)
+      <endpoint-slug>_<scenario>.yaml  # PLACEHOLDER — recorded by running cassette capture
+  vcr_characterization_test.go       # Test using go-vcr to replay cassettes
+```
+
+Write `vcr_characterization_test.go`:
+
+```go
+// AUTO-GENERATED VCR CHARACTERIZATION TEST SCAFFOLDING
+// Format: HTTP recording / VCR-style (Option C)
+//
+// BEFORE RUNNING:
+//   1. Install go-vcr: go get github.com/dnaeon/go-vcr/v3
+//   2. Run the Java service locally
+//   3. Set RECORD_MODE=true and run tests once to record cassettes
+//   4. Commit the cassette YAML files
+//   5. Run tests normally to replay cassettes against the Go service
+//
+// Run: go test -v ./... -run VCR
+
+package characterization_test
+
+import (
+    "net/http"
+    "testing"
+
+    "github.com/dnaeon/go-vcr/v3/cassette"
+    "github.com/dnaeon/go-vcr/v3/recorder"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+func TestVCR_<ServiceName>_Characterization(t *testing.T) {
+    t.Skip("NEEDS GOLDEN DATA: set JAVA_SERVICE_URL, run with RECORD_MODE=true against Java service first. See testdata/cassettes/ README.")
+
+    cassetteFile := "testdata/cassettes/create_booking_valid"
+
+    r, err := recorder.New(cassetteFile)
+    require.NoError(t, err)
+    defer r.Stop()
+
+    // TODO(human): point this at your Go service URL, not the Java service
+    // In record mode (cassette missing), it records against Java service
+    // In replay mode (cassette exists), it replays against Go service
+    client := &http.Client{Transport: r}
+    _ = client
+
+    // TODO(human): make HTTP requests using `client` and assert responses
+    assert.Fail(t, "implement VCR test body")
+}
+```
+
+---
+
+## Step 6: Output Checklist
+
+After generating scaffolding, print:
+
+```
+==========================================================================
+CHARACTERIZATION TEST SCAFFOLDING GENERATED
+Format: <test-format> (<A/B/C>)
+Output: <go-service-path>/
+
+WHAT YOU MUST DO NEXT TO CAPTURE GOLDEN DATA:
+
+[ ] 1. Start the Java service: <service-name>
+       (see service README or run: mvn spring-boot:run in <service-path>)
+
+[ ] 2. Set up test data in the database (if needed):
+       Run: psql -f testdata/sql/seed.sql <database-name>
+       (seed.sql must be written by the team — use synthetic data only, no real PII)
+
+[ ] 3. For each endpoint in <endpoint-list>:
+       Send the requests and capture responses:
+       See testdata/golden/README.md for exact curl commands (Format A)
+       OR follow Pact setup in contract/pact/README.md (Format B)
+       OR run with RECORD_MODE=true (Format C)
+
+[ ] 4. Remove t.Skip() calls as you populate each fixture
+
+[ ] 5. Run the tests against the Go service: go test -v ./...
+
+[ ] 6. All tests must pass before declaring the Go service ready for traffic
+==========================================================================
+```