wor-simple_crud 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 667672176b1c817bdcf1d9c5248e1b3701253d52f289a85bc2e4b3e632c47188
-  data.tar.gz: f03748bda6004b670a8989fed13d82e0c6e0e0ec6bd9323a1c4e43e786da4dfe
+  metadata.gz: e280efd8ead44768d16e0ba663e25a40d6972b53e253281d1c7eac0735421b64
+  data.tar.gz: 78625a2a759ca5fda1e7d41e421db92ed721f2e2c343524f0580cd810d32ac7a
 SHA512:
-  metadata.gz: '04257318d37af96ef5df3d17d2561dfad551cf3eaca51dc4630d7e7d9a7d19cd05852a4b31e00902ab245610d0e35379e3314586f18646afe3ddb246a17a1756'
-  data.tar.gz: 81b0fda087fc2723f8f7a6789f7f2542037b7054b36e9db8aed05eba03f5cdbcb0c38fdf45da85f60e9b3e67c58332118d73be257e5d16b108559eade35adba7
+  metadata.gz: 406a83cc98deaa7fa3ba5f7ccb9a12486a903b6aef81bddd0a5f4f9c595ffa64e7414cb8a718d4a4fe96f987fcefaf34a8b201cbe16aab4db2721eea0bd19397
+  data.tar.gz: 7177530ba1a01fcf526c406a14f3bf64bfcf895ce5675f4acca5f24f28c57db90859ddab43866d314f70e723cfebda24bc5930d64ac66a01d29bc6246792c04a

data/.gitignore

@@ -147,6 +147,11 @@ config/initializers/secret_token.rb
 ## Environment normalization:
 /.bundle
 /vendor/bundle
+# Appraisal gemfiles vendor their own bundles; never commit those.
+/gemfiles/.bundle/
+/gemfiles/vendor/
+# Local tooling logs.
+/.setting/
 
 # these should all be checked in to normalize the environment:
 # Gemfile.lock, .ruby-version, .ruby-gemset

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## Change log
 
+### V0.3.1
+
+Shared examples configuration:
+* Every setting can be overridden per controller or per example via `simple_crud:` RSpec metadata. Metadata takes precedence over `SimpleCrud::RSpec.configure` and the defaults, and all reads happen at example runtime, so per-resource tweaks need no around hooks, no global mutation and no restore logic.
+* New `model_attributes` setting (default: `{ owner_association => current_user }`) decides how records are built for the examples, so multi-key (`{ user:, project: }`), non-user-owned (`{ project: project }`) or owner-less models work without editing the shared examples.
+* Dedicated examples (`*_with_block`, `*_with_build`, `*_with_scope`) no longer assume the gem's dummy app: request params derive from `params_for`/`owner_params`, authentication wraps conditionally on the action's `authenticate:` option, and render-block actions are asserted on status and persistence effects only (a block's response body is app-defined by definition).
+* The finder/build dedicated families (`show/update/destroy with finder`, `not found with finder`, `new with build`) adapt to each action's declared options too: render-block actions are asserted success-only, `html: true` actions assert the rendered template or redirect, and plain JSON keeps the status/body assertions. Server-rendered apps no longer need to skip these families.
+* `index with scope` builds its records through new `scoped_attributes` (default: `model_attributes`) and `other_scoped_attributes` (default: `model_attributes.merge(owner_association => other_user)`) settings instead of hardcoding `owner_association => user`, so factories without that attribute keep working and multi-key models express their scope via metadata. The assertion follows the controller: `assigns(:records)` ids for `html: true`, the wor-paginate envelope for paginated JSON, and the bare serialized array otherwise.
+* Actions declared with a render block expose `block: true` in the controller metadata, and the shared examples treat them accordingly: failure/invalid paths assert persistence effects only (the block decides how the response is rendered), while default flows keep their pinned statuses/templates.
+* The base destroy example covers the failure path (record always kept; non-block flows respond 422 as JSON or re-render `show` as HTML).
+* New optional `created_record_check` setting: a lambda receiving the persisted record in the create/update success paths, to assert ownership/scope that `count == 1` alone can't catch.
+
 ### V0.3.0
 
 Server-rendered (HTML) support:
@@ -7,8 +19,9 @@ Server-rendered (HTML) support:
 * New `:new` action: builds a record, authorizes it, and renders `new.html.erb` (or returns JSON in API mode).
 
 Custom lookups, scoping and building:
-* `finder:` on `:show`/`:update`/`:destroy`: a `Proc`/lambda invoked with the controller's params, or a `Symbol` naming a class method on the model. Defaults to `klass.find(params[:id])`.
-* `build:` on `:new`/`:create` for owner-scoped or nested builds (`current_user.classrooms.build`); runs with the controller as `self`, and `:create` assigns the permitted params to the built record before saving.
+* `finder:` on `:show`/`:update`/`:destroy`/`:edit`: a `Proc`/lambda invoked with the controller's params, or a `Symbol` naming a class method on the model. Defaults to `klass.find(params[:id])`.
+* New `simple_crud_for :edit`: the find-instead-of-build twin of `:new`. It looks the record up (honoring `finder:`), authorizes it and renders `edit.html.erb` with `@record` in HTML mode, returning the record as JSON otherwise. A matching `simple crud for edit` shared example covers the authorized/denied, not-found and html/json/block paths.
+* `build:` on `:new`/`:create` for owner-scoped or nested builds (`current_user.projects.build`); runs with the controller as `self`, and `:create` assigns the permitted params to the built record before saving.
 * With `authorize: true`, `:index` paginates the Pundit `policy_scope` of the model (falling back to the full relation when no `Scope` is defined) instead of `klass.all`, with a per-action `scope: ->(user[, params]) { ... }` override.
 * `redirect:` on HTML-mode `:create`/`:update`/`:destroy`: a `Proc` called with the record, or a literal path, overriding the default success redirect.
 
@@ -17,6 +30,7 @@ Validation errors:
 
 Authorization changes:
 * Breaking: `authorize: true` now always enforces policy checks, including for `authenticate: false` actions, which reach policies with a `nil` user. Policies must tolerate a `nil` user.
+* Breaking: `:index` authorizes the model class instead of an unsaved instance, matching the Pundit/CanCanCan collection conventions. `index?` policies can no longer inspect record state (there is none), so write them against the user.
 * `SimpleCrud::Config.user_method` (default `:current_user`) selects the controller method providing the user to policies and scope lambdas, so apps with other conventions (`current_admin`, ...) need no shims.
 
 Adapter interfaces:

data/README.md

@@ -95,6 +95,7 @@ simple_crud_for :index
 simple_crud_for :create
 simple_crud_for :destroy
 simple_crud_for :new
+simple_crud_for :edit
 ```
 
 Each method supports different options, as in:
@@ -106,10 +107,10 @@ simple_crud_for :index, paginate: false, authorize: false, serializer: CustomSer
 - Authorize: whether it should check authorization via the configured authorization adapter (Pundit by default)
 - Authenticate: whether it should use Devise to check for a current_user
 - Serializer: specify a particular serializer you should use
-- Html: renders the action's ERB template instead of JSON (valid for `:index`, `:show`, `:new`, `:create`, `:update` and `:destroy`). Only meaningful in controllers that render templates
+- Html: renders the action's ERB template instead of JSON (valid for `:index`, `:show`, `:new`, `:edit`, `:create`, `:update` and `:destroy`). Only meaningful in controllers that render templates
 - Scope: only valid for `:index`. A `Proc`/`lambda` taking `current_user` (plus the controller's `params` if it takes a second argument) that returns the relation to list, overriding the default `policy_scope`. The user is resolved via `SimpleCrud::Config.user_method` (`:current_user` by default; set it to e.g. `:current_admin`)
-- Finder: only valid for `:show`, `:update` and `:destroy`. A `Proc`/`lambda` (invoked with the controller's params) or a `Symbol` naming a class method on the model, used to look up the record instead of `klass.find(params[:id])`.
-- Build: only valid for `:new` and `:create`. A `Proc`/`lambda` that builds the record (invoked with the controller as `self`, so `current_user`, `params` and any instance variables are available), for building nested or owner-scoped records like `current_user.classrooms.build`. `:create` then assigns the permitted params to the built record before saving
+- Finder: only valid for `:show`, `:update`, `:destroy` and `:edit`. A `Proc`/`lambda` (invoked with the controller's params) or a `Symbol` naming a class method on the model, used to look up the record instead of `klass.find(params[:id])`.
+- Build: only valid for `:new` and `:create`. A `Proc`/`lambda` that builds the record (invoked with the controller as `self`, so `current_user`, `params` and any instance variables are available), for building nested or owner-scoped records like `current_user.projects.build`. `:create` then assigns the permitted params to the built record before saving
 - Raise_on_invalid: only valid for `:create` and `:update`. Keeps the strict `create!`/`update!` semantics (raising on invalid input) instead of returning `422` with the validation errors
 - Redirect: only valid for HTML-mode `:create`, `:update` and `:destroy`. A `Proc`/`lambda` (called with the record) or a literal path used as the success redirect target. Defaults to the record (`:create`/`:update`) or the model's collection path (`:destroy`)
 
@@ -263,6 +264,7 @@ For server-rendered apps, `html: true` renders the action's ERB template instead
 - `:index` renders `index.html.erb` with the paginated records exposed as `@records` (pagination still applies, or use `paginate: false`).
 - `:show` renders `show.html.erb` with the record exposed as `@record` (custom `finder:` still applies).
 - `:new` builds a new record, authorizes it, and renders `new.html.erb` with it exposed as `@record`.
+- `:edit` looks the record up (honoring `finder:`), authorizes it, and renders `edit.html.erb` with it exposed as `@record`.
 - `:create` saves and redirects to the created record on success, or re-renders `new.html.erb` (with `@record` and its errors) on failure.
 - `:update` saves and redirects to the record on success, or re-renders `edit.html.erb` on failure.
 - `:destroy` destroys and redirects to the collection (`redirect_to Model`) on success, or re-renders `show.html.erb` if a callback aborts the destroy.
@@ -271,6 +273,7 @@ For server-rendered apps, `html: true` renders the action's ERB template instead
 simple_crud_for :index, html: true
 simple_crud_for :show, html: true
 simple_crud_for :new, html: true
+simple_crud_for :edit, html: true
 simple_crud_for :create, html: true
 simple_crud_for :update, html: true
 simple_crud_for :destroy, html: true
@@ -289,15 +292,22 @@ end
 ```
 
 #### Build
-`simple_crud_for :new` and `simple_crud_for :create` build the record with `klass.new`, which can't express owner-scoped or nested records (`current_user.classrooms.build`, `@classroom.assignments.build`). Pass a `build:` lambda; it runs with the controller as `self`, so `current_user`, `params` and any instance variables set by a `before_action` are available:
+`simple_crud_for :new` and `simple_crud_for :create` build the record with `klass.new`, which can't express owner-scoped or nested records (`current_user.projects.build`, `@project.tasks.build`). Pass a `build:` lambda; it runs with the controller as `self`, so `current_user`, `params` and any instance variables set by a `before_action` are available:
 
 ```ruby
-simple_crud_for :new, build: -> { current_user.classrooms.build }
-simple_crud_for :create, build: -> { current_user.classrooms.build }
+simple_crud_for :new, build: -> { current_user.projects.build }
+simple_crud_for :create, build: -> { @project.tasks.build }
 ```
 
 `:create` assigns the permitted params to the built record before saving, so the owner/parent association survives. `:update` keeps finding the record via the `finder:`.
 
+#### Edit
+`simple_crud_for :edit` is the find-instead-of-build twin of `:new`, the last hand-written CRUD action in server-rendered apps. It looks the record up (honoring `finder:` exactly like `:show`), authorizes it, and renders `edit.html.erb` with the record exposed as `@record`; in JSON mode it returns the record:
+
+```ruby
+simple_crud_for :edit, finder: ->(params) { Project.find_by!(slug: params[:slug]) }
+```
+
 #### Finder
 By default records are looked up by primary key via `klass.find(params[:id])`. The `finder:` option on `:show`, `:update` and `:destroy` replaces that with any lookup you want: pretty URLs (`resources :posts, param: :slug`), tokens, composite keys, or scoping by a parent resource. Pass a `Proc`/`lambda` that maps the controller's `params` to a record, or a `Symbol` naming a class method on the model that takes the params:
 
@@ -323,10 +333,11 @@ describe V1::Backoffice::AuthorsController do
 end
 ```
 
-The `create` and `update` examples cover the `422` response with validation errors (skipped when `raise_on_invalid: true`), and all base examples adapt to `html: true` controllers (asserting the rendered template/redirect instead of JSON). Controllers using the extra options can include their dedicated examples too:
+The `create` and `update` examples cover the `422` response with validation errors (skipped when `raise_on_invalid: true`, or whenever the action uses a render block, since the block decides how the response is rendered), and all base examples adapt to `html: true` controllers (asserting the rendered template/redirect instead of JSON). Controllers using the extra options can include their dedicated examples too:
 
 ```ruby
 include_examples 'simple crud for new'                    # the :new action
+include_examples 'simple crud for edit'                   # the :edit action
 include_examples 'simple crud for index with block'      # render block
 include_examples 'simple crud for index with scope'      # scope: ->(user) { ... }
 include_examples 'simple crud for show with block'       # render block on :show
@@ -359,8 +370,11 @@ SimpleCrud::RSpec.configure do |config|
   config.create_records = ->(klass, count, attributes) { count.times.map { klass.create!(attributes) } }
   config.params_for = ->(klass) { klass.new.attributes.slice('title') }
 
-  # The owner association and the validation this app's models enforce.
-  config.owner_association = :instructor
+  # The owner association used when building records for the examples
+  # (model_attributes defaults to `{ owner_association => current_user }`;
+  # override model_attributes directly for multi-key or non-user-owned models).
+  config.owner_association = :owner
+  config.model_attributes = -> { { owner: current_user } }
   config.required_attribute = :title
   config.required_error = "Title can't be blank"
 
@@ -371,24 +385,53 @@ SimpleCrud::RSpec.configure do |config|
   config.assert_html_template = false
 
   # Server-rendered apps usually use nested strong params
-  # (params.require(:classroom).permit(:name)); wrap request bodies under the
+  # (params.require(:task).permit(:name)); wrap request bodies under the
   # model's params key instead of posting flat params.
-  config.params_key = :classroom
+  config.params_key = :task
 
-  # Nested resources (/classrooms/:classroom_slug/assignments): extra params
+  # Nested resources (/projects/:project_slug/tasks): extra params
   # (e.g. the parent slug) added to every request.
-  config.route_params = -> { { classroom_slug: model.classroom_slug } }
+  config.route_params = -> { { project_slug: project.slug } }
 
   # Re-render the form with a 422 on validation failure (instead of 200).
   config.invalid_status = :unprocessable_entity
 
+  # How the 'simple crud for index with scope' example builds the records
+  # that match the controller's scope and the ones that must be excluded.
+  # Defaults derive from model_attributes (mine) plus an owner_association
+  # => other_user variant (theirs); override both when your scope keys on
+  # something other than the owner association.
+  config.scoped_attributes = -> { { project: project } }
+  config.other_scoped_attributes = -> { { project: other_project } }
+
   # Pundit policy and serializer class lookup.
   config.policy_class = ->(klass) { "#{klass}Policy".constantize }
   config.serializer_class = ->(model) { "#{model.class}Serializer".constantize }
+
+  # Optional extra assertions on the persisted record in the create/update
+  # success paths (catches regressions that save into the wrong parent).
+  config.created_record_check = ->(record) { expect(record.project).to eq(project) }
+end
+```
+
+Each setting has a sensible default, so you only override what differs. Callable settings (`current_user`, `authenticate`, `create_record`, `create_records`, `params_for`, `model_attributes`, `scoped_attributes`, `other_scoped_attributes`, `policy_class`, `serializer_class`) run in the example-group context, so they can call `request`, `create`, `current_user`, etc.; `created_record_check` receives the persisted record. The examples are controller-agnostic (they issue requests by action name, not hardcoded paths), so they work for namespaced and nested controllers alike. If you keep `assert_html_template` on (the default), add `gem 'rails-controller-testing'` for the `render_template` matcher.
+
+#### Per-controller overrides via metadata
+
+Any setting can also be overridden per controller (or per example) with `simple_crud:` metadata instead of globally, useful when the app matches the defaults except for one resource. Metadata wins over global config, and every read happens at example runtime, so there are no around hooks or state to restore:
+
+```ruby
+RSpec.describe TasksController, type: :controller, simple_crud: {
+  model_attributes: -> { { project: project } },
+  route_params: -> { { project_slug: project.slug } }
+} do
+  let(:project) { create(:project, owner: current_user) }
+
+  include_examples 'simple crud for show'
 end
 ```
 
-Each setting has a sensible default, so you only override what differs. Callable settings (`current_user`, `authenticate`, `create_record`, `create_records`, `params_for`, `policy_class`, `serializer_class`) run in the example-group context, so they can call `request`, `create`, `current_user`, etc. The examples are controller-agnostic (they issue requests by action name, not hardcoded paths), so they work for namespaced and nested controllers alike. If you keep `assert_html_template` on (the default), add `gem 'rails-controller-testing'` for the `render_template` matcher.
+Callable settings resolve in the example context, so their lambdas can close over the spec's `let`s; that's how records land in the same project the route params point at.
 
 ## Contributing
 

data/lib/simple_crud/action_lambdas.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  # Builds the lambda installed as each action declared with simple_crud_for.
+  module ActionLambdas
+    def crud_lambda_for_show(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        requested = SimpleCrudController.find_record(klass, self, parameters)
+
+        options = {}.merge(serializer: parameters[:serializer]).compact
+        SimpleCrudController.maybe_authorize(self, requested, parameters)
+        SimpleCrudController.render_show(self, requested, options, parameters, &block)
+      end
+    end
+
+    def crud_lambda_for_new(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        record = SimpleCrudController.build_record(self, klass, parameters)
+        SimpleCrudController.maybe_authorize(self, record, parameters)
+        SimpleCrudController.render_new(self, record, parameters, &block)
+      end
+    end
+
+    # The find-instead-of-build twin of :new.
+    def crud_lambda_for_edit(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        requested = SimpleCrudController.find_record(klass, self, parameters)
+        SimpleCrudController.maybe_authorize(self, requested, parameters)
+        SimpleCrudController.render_edit(self, requested, parameters, &block)
+      end
+    end
+
+    def crud_lambda_for_index(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        SimpleCrudController.maybe_authorize(self, klass, parameters)
+        options = {}.merge(each_serializer: parameters[:serializer]).compact
+        SimpleCrudController.render_index(self, klass, options, parameters, &block)
+      end
+    end
+
+    def crud_lambda_for_create(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        permitted_params = send("#{self.class.simple_crud_controller_model.to_s.underscore}_params")
+        record = SimpleCrudController.build_record(self, klass, parameters)
+        record.assign_attributes(permitted_params)
+        SimpleCrudController.maybe_authorize(self, record, parameters)
+        persist = ->(bang:) { bang ? record.save! : record.save }
+        options = { status: :created, failure_template: :new }
+        SimpleCrudController.save_and_render(self, record, parameters, options, persist, &block)
+      end
+    end
+
+    def crud_lambda_for_update(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        requested = SimpleCrudController.find_record(klass, self, parameters)
+        SimpleCrudController.maybe_authorize(self, requested, parameters)
+        permitted_params = send("#{self.class.simple_crud_controller_model.to_s.underscore}_params")
+        persist = ->(bang:) { bang ? requested.update!(permitted_params) : requested.update(permitted_params) }
+        options = { status: :ok, failure_template: :edit }
+        SimpleCrudController.save_and_render(self, requested, parameters, options, persist, &block)
+      end
+    end
+
+    def crud_lambda_for_destroy(klass, parameters = {}, &block)
+      lambda do
+        authenticate_user! if parameters[:authenticate]
+        requested = SimpleCrudController.find_record(klass, self, parameters)
+        SimpleCrudController.maybe_authorize(self, requested, parameters)
+        options = { status: :ok, failure_template: :show, redirect: parameters[:redirect] || klass }
+        persist = ->(bang:) { bang ? requested.destroy! : requested.destroy }
+        SimpleCrudController.persist_and_render(self, requested, parameters, options, persist, &block)
+      end
+    end
+  end
+end

data/lib/simple_crud/controller_helpers.rb

@@ -33,11 +33,20 @@ module SimpleCrud
     end
 
     def render_new(controller, record, parameters, &block)
+      render_form(controller, record, :new, parameters, &block)
+    end
+
+    def render_edit(controller, record, parameters, &block)
+      render_form(controller, record, :edit, parameters, &block)
+    end
+
+    def render_form(controller, record, template, parameters, &block)
       if parameters[:html] || block
         controller.instance_variable_set(:@record, record)
-        block ? controller.instance_exec(record, &block) : controller.render(:new)
+        block ? controller.instance_exec(record, &block) : controller.render(template)
       else
-        controller.render json: record
+        options = {}.merge(serializer: parameters[:serializer]).compact
+        controller.render({ json: record }.merge(options))
       end
     end
 

data/lib/simple_crud/rspec/config.rb

@@ -14,10 +14,10 @@ module SimpleCrud
     # Serializers), so apps on a different stack can override them via
     # SimpleCrud::RSpec.configure instead of editing the examples.
     #
-    # Callable settings (authenticate, current_user, create_record,
-    # create_records, attributes_for, policy_class, serializer_class) run in
-    # the example-group context, so they can call helpers such as `create`,
-    # `request` and `current_user`.
+    # Callable settings (authenticate, current_user, other_user,
+    # create_record, create_records, params_for, model_attributes,
+    # policy_class, serializer_class) run in the example-group context, so
+    # they can call helpers such as `create`, `request` and `current_user`.
     class Config
       DEFAULTS = {
         authenticate: lambda {
@@ -30,6 +30,18 @@ module SimpleCrud
         create_records: ->(klass, count, attributes) { create_list(klass, count, **attributes) },
         params_for: ->(klass) { attributes_for(klass) },
         owner_association: :user,
+        model_attributes: -> { owner_association ? { owner_association => current_user } : {} },
+        scoped_attributes: -> { model_attributes },
+        other_scoped_attributes: lambda {
+          attributes = model_attributes
+          if owner_association && !attributes.is_a?(Hash)
+            raise ArgumentError,
+                  'model_attributes must resolve to a Hash when owner_association is set; ' \
+                  'override other_scoped_attributes instead'
+          end
+
+          owner_association ? attributes.merge(owner_association => other_user) : {}
+        },
         required_attribute: :name,
         required_error: "Name can't be blank",
         finder_key: :slug,
@@ -39,7 +51,8 @@ module SimpleCrud
         unauthenticated_status: :unauthorized,
         assert_html_template: true,
         policy_class: ->(klass) { "#{klass}Policy".constantize },
-        serializer_class: ->(model) { "#{model.class}_serializer".classify.constantize }
+        serializer_class: ->(model) { "#{model.class}_serializer".classify.constantize },
+        created_record_check: nil
       }.freeze
 
       class << self

data/lib/simple_crud/rspec/helpers/authentication.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Current/other users, signing requests in and the owner association
+      # attributed to the current user.
+      module Authentication
+        def current_user
+          @current_user ||= instance_exec(&setting(:current_user))
+        end
+
+        def other_user
+          @other_user ||= instance_exec(&setting(:other_user))
+        end
+
+        def authenticate_request
+          instance_exec(&setting(:authenticate))
+        end
+
+        def owner_foreign_key
+          :"#{owner_association}_id"
+        end
+
+        # The owner association attributed to current_user, if the model has one.
+        def owner_params
+          owner_association ? { owner_foreign_key => current_user.id } : {}
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec/helpers/controller_options.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Definition-time introspection of the options each action was declared
+      # with via simple_crud_for (read from the controller's metadata).
+      module ControllerOptions
+        def get_option(method, option)
+          described_class.instance_variable_get(:@simple_crud_metadata)[method][option]
+        end
+
+        %i[paginate authorize authenticate serializer html finder scope build raise_on_invalid block].each do |option|
+          define_method("check_#{option}") { |method| get_option(method, option) }
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec/helpers/models.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Building the record under test and the params used to persist it.
+      module Models
+        def model_class
+          described_class.to_s.split('::')
+                         .last.sub('Controller', '').singularize.underscore
+        end
+
+        def model_class_object
+          model_class.classify.constantize
+        end
+
+        def model
+          @model ||= create_record(model_class, model_attributes)
+        end
+
+        def model_attributes
+          resolve(setting(:model_attributes))
+        end
+
+        def create_record(klass, attributes)
+          instance_exec(klass, attributes, &setting(:create_record))
+        end
+
+        def create_records(klass, count, attributes)
+          instance_exec(klass, count, attributes, &setting(:create_records))
+        end
+
+        def params_for(klass)
+          instance_exec(klass, &setting(:params_for))
+        end
+
+        def model_params
+          @model_params ||= params_for(model_class)
+        end
+
+        def model_serializer
+          defined?(serializer) ? serializer : instance_exec(model, &setting(:serializer_class))
+        end
+
+        def rendered_record
+          controller.instance_variable_get(:@record)
+        end
+
+        def rendered_records
+          controller.instance_variable_get(:@records)
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec/helpers/policies.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Locating the policy object for the model under test and stubbing it
+      # to allow or deny.
+      module Policies
+        def policy_class_object
+          instance_exec(model_class_object, &setting(:policy_class))
+        end
+
+        def make_policies_fail(method)
+          allow(policy_class_object).to receive(:new)
+            .and_return(instance_double(policy_class_object, "#{method}?" => false))
+        end
+
+        def make_policies_succeed(method)
+          allow(policy_class_object).to receive(:new)
+            .and_return(instance_double(policy_class_object, "#{method}?" => true))
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec/helpers/requests.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Request params and format helpers shared by every action example.
+      module Requests
+        # :unprocessable_entity was renamed :unprocessable_content in Rack 3.1.
+        # Resolve the current Rack's canonical symbol for 422.
+        def unprocessable_status
+          Rack::Utils::SYMBOL_TO_STATUS_CODE.invert[422]
+        end
+
+        def request_format(action)
+          check_html(action) ? :html : :json
+        end
+
+        # Extra params (e.g. a parent slug) added to every request, for nested
+        # resources like /projects/:project_slug/tasks.
+        def route_params
+          resolve(setting(:route_params))
+        end
+
+        def with_route_params(attrs)
+          route_params.merge(attrs)
+        end
+
+        # The params that identify a record for the given action, using the
+        # configured finder_key when the action has a custom finder.
+        def record_param(action, record, not_found: false)
+          key = check_finder(action) ? finder_key : :id
+          value = not_found ? "nonexistent-#{key}" : record.public_send(key)
+          { key => value }
+        end
+
+        # Wraps a request body under the model's strong-params key when
+        # params_key is configured (nested strong params), else passes it flat.
+        def body_params(attrs)
+          key = params_key
+          key ? { key => attrs } : attrs
+        end
+      end
+    end
+  end
+end

data/lib/simple_crud/rspec/helpers/settings.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SimpleCrud
+  module RSpec
+    module Helpers
+      # Settings resolution: `simple_crud:` example-group metadata first,
+      # falling back to the app-wide SimpleCrud::RSpec::Config singleton.
+      module Settings
+        def config
+          SimpleCrud::RSpec::Config.instance
+        end
+
+        def simple_crud_settings
+          source = ::RSpec.current_example ? ::RSpec.current_example.metadata : metadata
+          source[:simple_crud] || {}
+        end
+
+        def setting(name)
+          simple_crud_settings.fetch(name) { config.public_send(name) }
+        end
+
+        def resolve(value)
+          value.is_a?(Proc) ? instance_exec(&value) : value
+        end
+
+        %i[owner_association required_attribute required_error finder_key params_key invalid_status
+           unauthenticated_status assert_html_template scoped_attributes other_scoped_attributes].each do |name|
+          define_method(name) { resolve(setting(name)) }
+        end
+
+        def created_record_check
+          setting(:created_record_check)
+        end
+
+        # Runs the block with a config setting temporarily overridden, restoring
+        # the original value afterwards (even if the block raises). Useful when
+        # a controller's spec needs a different setting than the app-wide default.
+        def with_config_override(setting, value)
+          config_instance = SimpleCrud::RSpec::Config.instance
+          original = config_instance.public_send(setting)
+          SimpleCrud::RSpec.configure { |c| c.public_send("#{setting}=", value) }
+          yield
+        ensure
+          SimpleCrud::RSpec.configure { |c| c.public_send("#{setting}=", original) }
+        end
+      end
+    end
+  end
+end