belt 0.4.8 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21aaed39c7b6868b8c6f370cbc97a686bf369f7d3fe7a03c56b850c1bc49fd62
-  data.tar.gz: 8825ef22ce89cee45435dcd1e7b405c954c9f630e90f569ee0d575de33db5b49
+  metadata.gz: 5247752ecef8dc1c7241d3098a0896005f1533b2e1315914bf58c7534fa315f6
+  data.tar.gz: 429bb361f14e70fd06988c6f0b026988e6623467ded6b8a3b7ee27849f607452
 SHA512:
-  metadata.gz: 9bdf007e3adcc59dd1e852f2d9563002416272ae4f954ce72231856bead07c261cc6bad6a86a8b6bbdbc6a2896b321eb717dcf5f70bda7e77cc2538ed67b2970
-  data.tar.gz: 95c20325ca7427776e6c08dbf9c6e2ad3a8dacb4293339bf24cb48dc74021a887dfd0152865a0cc295c311314047f605119e22ea8b293ba9e9dbb977a0a8c549
+  metadata.gz: da12badab39e69547f46b13c833c59a2a61902e62ba9a0442804586aaff9e7c8fe87bca9af9ffa970ea2e0ed68d0b9cc03b1721b71092661ec7d60fede9cb58f
+  data.tar.gz: 13984899af7ad0f1b0e2badb0cc244a084ad75856601b0bde24b4a03eedab642dfbb8d03016392b8d941733861f5c3bb9de79ebab7e0ba17c74dca42c96ba1b8

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.0
+
+### Added
+
+- **In-process e2e test harness (`require 'belt/testing'`).** Belt now ships the real
+  request path as a reusable test tier: a synthetic API Gateway event routed through the
+  real `Belt::ActionRouter` — no AWS, no HTTP server, no browser. It sits between
+  controller unit tests (which dispatch an action directly and never touch routing) and
+  full cloud e2e. `Belt::Testing::E2E::Client` wraps one router and returns a parsed
+  `Response` (`status` / `headers` / `body` / `json`, with `ok?` and `[]`);
+  `Belt::Testing::E2E::Helpers` mixes `api_get` / `api_post` / `api_put` / `api_patch` /
+  `api_delete` / `api_request` and a `cognito_claims` builder into `Minitest::Test` or
+  RSpec example groups; and `Belt::Testing::E2E.manifest_from_belt_routes(app_root:)`
+  builds the router manifest from the app's own `belt routes -f json` so the harness can't
+  drift from Belt's route-building internals. The module is opt-in and never loaded by
+  `require 'belt'`, so it stays out of the production Lambda path. App-specific seams
+  (DynamoDB Local, Cognito claims, external services like Bedrock/Stripe/S3) stay in the
+  app's own test boot — Belt owns only the generic request mechanics. See
+  `belt explain testing`.
+
 ## 0.4.8
 
 ### Added

data/README.md

@@ -731,6 +731,46 @@ puts "Created post: #{post.id}"
 
 Refuses to run against an environment that already has data (pass `--force` to override). `belt new` scaffolds a starter `config/seeds.rb`. See `belt explain data_seeding` for details.
 
+## Testing
+
+Belt ships an in-process **end-to-end harness** that drives the real router — no AWS, no HTTP server, no browser. It's the tier between controller unit tests (dispatch an action directly, never touch routing) and full cloud e2e (needs a deployed stack).
+
+Opt-in — it is **not** loaded by `require 'belt'`, so it never ships in the production Lambda path:
+
+```ruby
+require "belt"
+require "belt/testing"
+```
+
+The harness builds a synthetic API Gateway event and routes it through the real `Belt::ActionRouter`, exactly as API Gateway delivers it: the router finds the route, extracts path params, instantiates the real controller, and runs the real `before_action` chain. Router, controllers, models, validations, and authorization are **real**; DynamoDB (e.g. DynamoDB Local), Cognito (a claims hash), and external services stay seams you wire in your own test boot.
+
+```ruby
+# e2e_helper.rb — after booting your app (ENV, require 'belt', models, controllers, DynamoDB Local)
+router = Belt::ActionRouter.new(
+  routes:  Belt::Testing::E2E.manifest_from_belt_routes(app_root: APP_ROOT),
+  gateway: "api"
+)
+Belt::Testing::E2E.client = Belt::Testing::E2E::Client.new(router: router)
+```
+
+```ruby
+class ProjectsE2ETest < Minitest::Test
+  include Belt::Testing::E2E::Helpers
+
+  def test_creates_a_project
+    res = api_post("/projects", body: { slug: "alpha" }, claims: cognito_claims(groups: "admins"))
+    assert_equal 201, res.status
+    assert_equal "alpha", res["project"]["slug"]
+  end
+
+  def test_rejects_anonymous
+    assert_equal 401, api_get("/projects").status
+  end
+end
+```
+
+`api_get` / `api_post` / `api_put` / `api_patch` / `api_delete` (and `api_request`) accept `body:`, `claims:`, `token:`, `headers:`, and `query:`. The returned `Response` exposes `status`, `headers`, `body`, `json`, `ok?`, and `[]` (a top-level key from the parsed JSON body). Full details — the real-vs-seamed boundary, per-test clients, and keeping the tier out of your normal suite — in `belt explain testing`.
+
 ## Plugins
 
 Belt is designed to stay lean. Optional capabilities ship as **separate gems** that plug into the CLI and runtime the same way Rails engines and generators do.

data/lib/belt/cli/explain_command.rb

@@ -51,7 +51,13 @@ module Belt
         'db:seed' => 'data_seeding',
         'db:copy' => 'data_seeding',
         'copy' => 'data_seeding',
-        'db_copy' => 'data_seeding'
+        'db_copy' => 'data_seeding',
+        'e2e' => 'testing',
+        'test' => 'testing',
+        'tests' => 'testing',
+        'harness' => 'testing',
+        'spec' => 'testing',
+        'specs' => 'testing'
       }.freeze
 
       def self.run(args)
@@ -114,6 +120,7 @@ module Belt
             irb, repl                 → console
             seeds, seed, db:seed      → data_seeding
             db:copy, copy             → data_seeding
+            e2e, test, harness        → testing
 
           Examples:
             belt explain routing

data/lib/belt/docs/testing.md

@@ -0,0 +1,145 @@
+# Testing
+
+Belt ships an in-process **end-to-end harness** that drives the real router — no AWS, no
+HTTP server, no browser. It's the tier between controller unit tests (which dispatch an
+action directly and never touch routing) and full cloud e2e (which needs a deployed stack).
+
+Load it opt-in — it is **not** required by `require 'belt'`, so it never ships in the
+production Lambda path:
+
+```ruby
+require 'belt'
+require 'belt/testing'
+```
+
+## What it exercises
+
+The harness builds a synthetic API Gateway proxy event (method, path, body, and a
+`requestContext` carrying Cognito-style claims) and routes it through the real
+`Belt::ActionRouter` — exactly as API Gateway delivers it in production. The router finds
+the route, extracts path params, resolves and instantiates the real controller, and runs
+the real `before_action` chain. You assert on the HTTP-shaped response.
+
+| Layer | In the harness |
+|-------|----------------|
+| Router, controllers, models, validations, authorization | **Real** |
+| DynamoDB | Your choice (e.g. DynamoDB Local) — wired in your own test boot |
+| Cognito | A claims hash in `requestContext.authorizer.claims` (the seam API Gateway's authorizer fills in production) |
+| API Gateway | The synthetic event **is** the seam — the router is what APIGW dispatches to |
+
+Anything genuinely external (Cognito token verification, Bedrock, Stripe, S3) stays a seam
+you stub in your own boot file. Belt owns the generic request mechanics; your app owns its
+data-store lifecycle and external stubs.
+
+## The pieces
+
+- **`Belt::Testing::E2E::Client`** — wraps one `Belt::ActionRouter`, builds synthetic
+  events, dispatches, and returns a `Response`.
+- **`Belt::Testing::E2E::Response`** — a parsed `{ status, headers, body, json }` struct
+  with `ok?` and `[]` (reads a top-level key out of the parsed JSON body).
+- **`Belt::Testing::E2E::Helpers`** — a mixin for `Minitest::Test` or RSpec example groups
+  giving you `api_get` / `api_post` / `api_put` / `api_patch` / `api_delete` / `api_request`
+  plus a `cognito_claims` builder.
+- **`Belt::Testing::E2E.manifest_from_belt_routes(app_root:)`** — loads the route manifest
+  via your app's own `belt routes -f json`, the same canonical path the deployed Lambda's
+  manifest comes from, so the harness can't drift from Belt's route-building internals.
+
+## Setup
+
+Build the router once per process from your app's real manifest, then expose a client:
+
+```ruby
+require 'belt'
+require 'belt/testing'
+
+# ... boot your app: set test ENV, require 'belt', load models + controllers,
+#     point Aws::DynamoDB::Client at DynamoDB Local, etc. ...
+
+router = Belt::ActionRouter.new(
+  routes:  Belt::Testing::E2E.manifest_from_belt_routes(app_root: APP_ROOT),
+  gateway: 'api'
+)
+Belt::Testing::E2E.client = Belt::Testing::E2E::Client.new(router: router)
+```
+
+## Writing tests
+
+```ruby
+class ProjectsE2ETest < Minitest::Test
+  include Belt::Testing::E2E::Helpers
+
+  def test_lists_projects_for_an_admin
+    res = api_get('/projects', claims: cognito_claims(groups: 'admins'))
+
+    assert res.ok?                          # 2xx
+    assert_equal 200, res.status
+    assert_kind_of Array, res['projects']   # top-level key out of the JSON body
+  end
+
+  def test_creates_a_project
+    res = api_post('/projects', body: { slug: 'alpha', name: 'Alpha' },
+                                claims: cognito_claims(groups: 'admins'))
+
+    assert_equal 201, res.status
+    assert_equal 'alpha', res['project']['slug']
+
+    # The write really happened — re-read it through the router.
+    show = api_get('/projects/alpha', claims: cognito_claims(groups: 'admins'))
+    assert show.ok?
+  end
+
+  def test_rejects_an_unauthenticated_request
+    res = api_get('/projects')   # no claims → unauthenticated
+    assert_equal 401, res.status
+  end
+end
+```
+
+### Request options
+
+Every `api_*` helper (and `Client#request`) accepts:
+
+| Option | Meaning |
+|--------|---------|
+| `body:` | request body as a **parsed Hash** (the LambdaHandler JSON-parses it in production) |
+| `claims:` | Cognito claims hash injected into `requestContext.authorizer.claims`; omit for an unauthenticated request |
+| `token:` | a Bearer token (e.g. an API key) set as the `Authorization` header, for non-Cognito auth |
+| `headers:` | extra request headers |
+| `query:` | query string parameters (`event['queryStringParameters']`) |
+
+### Claims
+
+`cognito_claims` builds the hash API Gateway's authorizer would inject:
+
+```ruby
+cognito_claims                                  # { 'sub' => 'e2e-user-sub', 'email' => '...' }
+cognito_claims(sub: 'u-1', groups: 'admins')    # platform staff
+cognito_claims(groups: %w[admins editors])      # array → space-joined 'cognito:groups'
+cognito_claims(tenant: 't-1')                   # extra claims merge straight in
+```
+
+## Per-test client
+
+By default the helpers use the process-wide `Belt::Testing::E2E.client`. To use a different
+client (e.g. a second gateway), override `#e2e_client` in your test base class:
+
+```ruby
+class OpsE2ETest < Minitest::Test
+  include Belt::Testing::E2E::Helpers
+
+  def e2e_client
+    @e2e_client ||= Belt::Testing::E2E::Client.new(router: OPS_ROUTER)
+  end
+end
+```
+
+## Keeping it out of the normal suite
+
+The harness needs the **real** Belt stack (`require 'belt'`). If your unit suite shadows
+`BeltController::Base` with a stub, keep the e2e tier in its own directory (e.g. `e2e/`,
+not `spec/`) and run it as its own process so the two don't collide:
+
+```bash
+cd lambda
+bundle exec ruby -Ie2e -e "Dir.glob('e2e/**/*_test.rb').each { |f| require File.expand_path(f) }"
+```

data/lib/belt/testing/e2e.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Belt
+  module Testing
+    # In-process end-to-end harness — the real request path, no AWS.
+    #
+    # Most backend tests stop at the controller: they instantiate a controller and
+    # dispatch an action directly. That proves action logic, but it never exercises the
+    # router, the route manifest, path-param extraction, or the Lambda-shaped event the
+    # controller actually receives in production.
+    #
+    # This harness closes that gap. It drives the REAL {Belt::ActionRouter} with a
+    # synthetic API Gateway proxy event — method, path, body, and a requestContext
+    # carrying Cognito-style claims — exactly as API Gateway would deliver it. The router
+    # finds the route, extracts path params, instantiates the real controller, and runs
+    # the real before_action chain. You assert on the HTTP-shaped response.
+    #
+    # What's real vs. seamed (the deliberate boundary):
+    #   - Router, controllers, models, validations, authorization .... REAL
+    #   - DynamoDB ............................................ your choice (e.g. DynamoDB Local)
+    #   - Cognito ............................................ a claims hash in requestContext
+    #                                                          (the seam API Gateway's
+    #                                                          authorizer fills in production)
+    #   - API Gateway ........................................ the synthetic event IS the seam
+    #
+    # The harness is framework-agnostic: use the {Client} directly, or mix {Helpers}
+    # into your Minitest::Test / RSpec example group for `api_get`/`api_post`/... sugar.
+    #
+    # @example Minitest
+    #   router = Belt::ActionRouter.new(
+    #     routes: Belt::Testing::E2E.manifest_from_belt_routes(app_root: APP_ROOT),
+    #     gateway: 'api'
+    #   )
+    #   Belt::Testing::E2E.client = Belt::Testing::E2E::Client.new(router: router)
+    #
+    #   class ProjectsE2ETest < Minitest::Test
+    #     include Belt::Testing::E2E::Helpers
+    #
+    #     def test_create_project
+    #       res = api_post('/projects', body: { slug: 'x' }, claims: cognito_claims(groups: 'admins'))
+    #       assert res.ok?
+    #       assert_equal 'x', res['project']['slug']
+    #     end
+    #   end
+    module E2E
+      # A parsed response from the router. `json` is the body parsed as JSON (Hash) when
+      # possible; `[]` reads a top-level key out of that parsed body.
+      Response = Struct.new(:status, :headers, :body, :json, keyword_init: true) do
+        def ok?
+          status.is_a?(Integer) && status.between?(200, 299)
+        end
+
+        def [](key)
+          json&.[](key.to_s)
+        end
+      end
+
+      class << self
+        # A process-wide default client, so {Helpers} works without per-test setup.
+        # Assign one after booting your stack and building a router.
+        attr_accessor :client
+
+        # Build a route manifest from the app's own `belt routes -f json`.
+        #
+        # This is the app's canonical, supported way to produce a manifest — the same
+        # path the deployed Lambda's manifest comes from — so the harness can't drift
+        # from Belt's route-building internals.
+        #
+        # @param app_root [String] directory to run `belt routes` from (the app's `lambda/`)
+        # @param command [Array<String>] override the command (mainly for testing)
+        # @return [Array<Hash>] routes shaped as { verb:, path:, controller:, action: }
+        def manifest_from_belt_routes(app_root:, command: %w[bundle exec belt routes -f json])
+          require 'open3'
+          out, err, status = Open3.capture3(*command, chdir: app_root)
+          raise Error, "`#{command.join(' ')}` failed (#{status.exitstatus}): #{err.strip}" unless status.success?
+
+          parse_manifest(out)
+        end
+
+        # Parse the JSON produced by `belt routes -f json` into the manifest shape the
+        # router expects. Public so callers that already have the JSON (CI artifact,
+        # cached file) can reuse it without shelling out.
+        #
+        # @param json [String] output of `belt routes -f json`
+        # @return [Array<Hash>]
+        def parse_manifest(json)
+          JSON.parse(json).fetch('routes').map do |r|
+            {
+              verb: r['verb'],
+              path: r['path'],
+              controller: r['controller'],
+              action: r['action']
+            }
+          end
+        rescue KeyError => e
+          raise Error, "belt routes JSON missing expected key: #{e.message}"
+        end
+      end
+
+      # Raised when the harness can't do its job (manifest load failure, missing client).
+      class Error < StandardError; end
+
+      # Drives a {Belt::ActionRouter} with synthetic API Gateway proxy events.
+      #
+      # One client wraps one router. Build it once per process (routing is immutable) and
+      # reuse it across tests — isolation comes from your data-store teardown, not from
+      # rebuilding the router.
+      class Client
+        attr_reader :router
+
+        # @param router [Belt::ActionRouter] the real router to dispatch through
+        def initialize(router:)
+          @router = router
+        end
+
+        # Issue a request through the real router.
+        #
+        # @param method [Symbol, String] HTTP verb (:get, :post, ...)
+        # @param path [String] request path, e.g. '/projects/ws-1'
+        # @param body [Hash, nil] request body, already parsed (as the LambdaHandler
+        #   delivers it in production). `nil` becomes `{}` inside the controller.
+        # @param claims [Hash, nil] Cognito claims the API Gateway authorizer would inject
+        #   into `requestContext.authorizer.claims`. `nil` means an unauthenticated request.
+        # @param token [String, nil] a Bearer token (e.g. an API key) set as the
+        #   Authorization header, for non-Cognito auth paths.
+        # @param headers [Hash] extra request headers.
+        # @param query [Hash, nil] query string parameters.
+        # @return [Response]
+        # rubocop:disable Metrics/ParameterLists -- these are the request's distinct, documented dimensions
+        def request(method, path, body: nil, claims: nil, token: nil, headers: {}, query: nil)
+          # rubocop:enable Metrics/ParameterLists
+          event = {
+            'httpMethod' => method.to_s.upcase,
+            'path' => path,
+            'headers' => build_headers(headers, token),
+            'pathParameters' => {},
+            'queryStringParameters' => query,
+            'requestContext' => request_context(claims)
+          }
+
+          result = router.route(event: event, body: body)
+          parse_response(result)
+        end
+
+        def get(path, **)    = request(:get, path, **)
+        def post(path, **)   = request(:post, path, **)
+        def put(path, **)    = request(:put, path, **)
+        def patch(path, **)  = request(:patch, path, **)
+        def delete(path, **) = request(:delete, path, **)
+
+        private
+
+        def build_headers(headers, token)
+          h = (headers || {}).dup
+          h['Authorization'] = "Bearer #{token}" if token
+          h
+        end
+
+        def request_context(claims)
+          return {} if claims.nil?
+
+          { 'authorizer' => { 'claims' => claims } }
+        end
+
+        # The real controller always returns a Lambda-shaped Hash:
+        # { statusCode:, headers:, body: <JSON string> }. So does the router's own error
+        # path. Normalize into a Response, tolerating string or symbol keys.
+        def parse_response(result)
+          status  = result[:statusCode] || result['statusCode']
+          headers = result[:headers] || result['headers'] || {}
+          raw     = result[:body] || result['body']
+
+          json =
+            begin
+              raw.is_a?(String) && !raw.empty? ? JSON.parse(raw) : nil
+            rescue JSON::ParserError
+              nil
+            end
+
+          Response.new(status: status, headers: headers, body: raw, json: json)
+        end
+      end
+
+      # Mixin for test classes (Minitest::Test or RSpec example groups).
+      #
+      # Provides `api_get`/`api_post`/`api_put`/`api_patch`/`api_delete`/`api_request`
+      # delegating to a client, plus a `cognito_claims` builder. By default it uses the
+      # process-wide {E2E.client}; override {#e2e_client} to supply a per-test client.
+      module Helpers
+        # The client requests route through. Override in your test base class to use a
+        # different client than the process-wide default.
+        #
+        # @return [Client]
+        def e2e_client
+          E2E.client || raise(Error, 'No Belt::Testing::E2E client configured. ' \
+                                     'Set Belt::Testing::E2E.client or override #e2e_client.')
+        end
+
+        def api_request(method, path, **) = e2e_client.request(method, path, **)
+        def api_get(path, **)             = e2e_client.get(path, **)
+        def api_post(path, **)            = e2e_client.post(path, **)
+        def api_put(path, **)             = e2e_client.put(path, **)
+        def api_patch(path, **)           = e2e_client.patch(path, **)
+        def api_delete(path, **)          = e2e_client.delete(path, **)
+
+        # Build a Cognito claims hash — what API Gateway's authorizer injects for an
+        # authenticated human.
+        #
+        # @param sub [String] the Cognito subject (user id)
+        # @param email [String, nil] the user's email claim
+        # @param groups [String, Array<String>, nil] `cognito:groups` (platform roles).
+        #   Belt reads this as a space/comma-delimited string; an array is joined with ' '.
+        # @param extra [Hash] any additional claims to merge in
+        # @return [Hash]
+        def cognito_claims(sub: 'e2e-user-sub', email: 'user@example.com', groups: nil, **extra)
+          claims = { 'sub' => sub }
+          claims['email'] = email if email
+          claims['cognito:groups'] = groups.is_a?(Array) ? groups.join(' ') : groups if groups
+          claims.merge(extra.transform_keys(&:to_s))
+        end
+      end
+    end
+  end
+end

data/lib/belt/testing.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Belt's test support. Opt-in: this is NOT loaded by `require 'belt'`, so it never ships
+# in the production Lambda path. Require it from your test harness instead:
+#
+#   require 'belt'
+#   require 'belt/testing'
+#
+# See Belt::Testing::E2E for the in-process, real-router end-to-end harness.
+
+require_relative 'action_router'
+require_relative 'testing/e2e'
+
+module Belt
+  # Namespace for Belt's test-support helpers (opt-in via `require 'belt/testing'`).
+  module Testing
+  end
+end

data/lib/belt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belt
-  VERSION = '0.4.8'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: belt
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.5.0
 platform: ruby
 authors:
 - Stowzilla
@@ -173,6 +173,7 @@ files:
 - lib/belt/docs/plugins.md
 - lib/belt/docs/routing.md
 - lib/belt/docs/structure.md
+- lib/belt/docs/testing.md
 - lib/belt/errors.rb
 - lib/belt/helpers/cors_origin.rb
 - lib/belt/helpers/error_logging.rb
@@ -186,6 +187,8 @@ files:
 - lib/belt/root.rb
 - lib/belt/route_dsl.rb
 - lib/belt/table_inference.rb
+- lib/belt/testing.rb
+- lib/belt/testing/e2e.rb
 - lib/belt/version.rb
 - lib/belt/views/welcome/show.html.erb
 - lib/belt_controller/base.rb