Rails request specs with RSpec and FactoryBot

# AGENTS.md: Rails app tested with RSpec

A Rails 8.1 app whose tests are RSpec (`rspec-rails`) with FactoryBot. Check `Gemfile.lock` for exact versions before
using an API.

## Commands
- Tests: `bundle exec rspec` (random order). One file: `bundle exec rspec spec/requests/projects_spec.rb:42`.
- Lint: `bundle exec rubocop` (rubocop-rails-omakase plus rubocop-rspec and rubocop-rspec_rails).
- Migrations: `bin/rails db:migrate`, then commit `db/schema.rb`. The test database follows the schema
  (`maintain_test_schema!`).
- Done means: the new specs fail without the change and pass with it, and the whole suite and rubocop are green.

## Rules
- Every controller action has request specs (`spec/requests/`): the happy path, the validation error (422,
  `:unprocessable_content`), missing params (400), and another user's record (404). Use the `rspec-request-spec`
  skill.
- Strong params with `params.expect(model: [...])`. Never permit ownership or role fields. Set them from the
  authenticated user.
- Scope every lookup to the current user or account (`current_user.projects.find(...)`). An unscoped `Model.find`
  in a controller is a bug.
- Model specs for validations and scopes use `build` or `build_stubbed`, and hit the database only when the
  behaviour needs it.
- FactoryBot factories hold the minimum valid record. Variants go in traits. Unique fields use `sequence`.
- No controller specs, no `allow_any_instance_of`, no `sleep`, no real HTTP in specs.
- Do not change `.rspec`, `spec_helper.rb` or `rails_helper.rb` to make a failing spec pass.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `rspec-request-spec`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rails request specs with RSpec and FactoryBot" v1.0.0 — https://loadout.jnw-it.com/loadouts/rails-rspec/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `rspec-request-spec`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rails request specs with RSpec and FactoryBot" v1.0.0 — https://loadout.jnw-it.com/loadouts/rails-rspec/ -->

---
name: rspec-request-spec
description: Write RSpec request specs for a Rails JSON endpoint with FactoryBot, covering the happy path, validation errors, missing params and access scoping, then run rspec and rubocop-rspec. Use when adding or changing a controller action, route or API response in a Rails app tested with RSpec.
---

# Request specs for a Rails endpoint

The references hold a complete, passing set: `projects_controller.rb`, `project.rb`, `projects_factory.rb`
(goes in `spec/factories/projects.rb`), `projects_spec.rb` (goes in `spec/requests/`), `rails_helper.rb`,
`spec_helper.rb` and `rubocop.yml`.

## What every endpoint's spec covers

1. **Happy path**, with status and the body fields that matter: `response.parsed_body`, compared with `eq` or
   `include`.
2. **Validation failure**: `have_http_status(:unprocessable_content)` and the error message for the field.
3. **Missing or malformed params**: `params.expect` raises, and Rails answers 400.
4. **Scoping**: another user's record returns 404, and the list never includes it. The spec catches an unscoped
   `find`.
5. **Mass assignment**: a forbidden attribute in the body (`owner_id`, `admin`, `role`) is ignored.
6. **Side effects**: `expect { ... }.to change(Model, :count).by(n)` for creates and deletes.

## How to write them

- Request specs (`spec/requests/`), not controller specs. They go through routing, middleware and params parsing.
- Use `as: :json` for JSON bodies. With `wrap_parameters`, a flat JSON body is wrapped under the model key, so test a
  missing key with a form post.
- Use `create` only when the database is needed, and `build` or `build_stubbed` in model and unit specs. Use a
  factory `sequence` for unique fields and traits (`:archived`) for variants. Never use a fixed id.
- `let` for data an example uses. Create records inside the example when their order or count is the point.
- Follow arrange, act, assert with blank lines between, and one behaviour per example. Name examples for the
  behaviour ("hides another owner's project behind a 404"), not the implementation.
- No `sleep`, no real network and no `allow_any_instance_of`. Freeze time with `travel_to` when a time is asserted.

## Run

```bash
bundle exec rspec spec/requests/projects_spec.rb
bundle exec rspec                       # the whole suite, random order
bundle exec rubocop app spec
```

Random order is on (`config.order = :random`). If a spec fails only in some orders, it leaks state. Fix the leak;
do not pin the seed.

## Done means

The new examples fail before the change and pass after it. The whole suite and rubocop (omakase, rubocop-rspec and
rubocop-rspec_rails) are green.

# JSON API for projects, scoped to the current owner. In a real app the owner
# comes from authentication; here it is a header so the specs can show the scoping.
class ProjectsController < ApplicationController
  before_action :require_owner
  before_action :set_project, only: %i[show update destroy]

  def index
    render json: Project.owned_by(@owner_id).order(:name).limit(100)
  end

  def show
    render json: @project
  end

  def create
    project = Project.new(project_params.merge(owner_id: @owner_id))
    if project.save
      render json: project, status: :created, location: project
    else
      render json: { errors: project.errors }, status: :unprocessable_content
    end
  end

  def update
    if @project.update(project_params)
      render json: @project
    else
      render json: { errors: @project.errors }, status: :unprocessable_content
    end
  end

  def destroy
    @project.destroy!
    head :no_content
  end

  private
    def require_owner
      @owner_id = Integer(request.headers.fetch("X-Owner-Id"))
    rescue KeyError, ArgumentError
      head :unauthorized
    end

    # Another owner's project is a 404, not a 403: do not confirm that it exists.
    def set_project
      @project = Project.owned_by(@owner_id).find_by(id: params[:id])
      head :not_found unless @project
    end

    def project_params
      params.expect(project: %i[name status])
    end
end

class Project < ApplicationRecord
  STATUSES = %w[active archived].freeze

  validates :name, presence: true, length: { maximum: 80 }, uniqueness: { scope: :owner_id }
  validates :status, inclusion: { in: STATUSES }
  validates :owner_id, presence: true

  scope :owned_by, ->(owner_id) { where(owner_id: owner_id) }
end

FactoryBot.define do
  factory :project do
    sequence(:name) { |n| "Project #{n}" }
    status { "active" }
    owner_id { 1 }

    trait :archived do
      status { "archived" }
    end
  end
end

require "rails_helper"

RSpec.describe "Projects API" do
  let(:owner_headers) { { "X-Owner-Id" => "1" } }
  let(:json) { response.parsed_body }

  describe "GET /projects" do
    it "lists only the current owner's projects, by name" do
      create(:project, name: "Beta")
      create(:project, name: "Alpha")
      create(:project, name: "Not mine", owner_id: 2)

      get "/projects", headers: owner_headers

      expect(response).to have_http_status(:ok)
      expect(json.pluck("name")).to eq(%w[Alpha Beta])
    end

    it "rejects a request with no owner" do
      get "/projects"

      expect(response).to have_http_status(:unauthorized)
    end
  end

  describe "GET /projects/:id" do
    it "hides another owner's project behind a 404" do
      other = create(:project, owner_id: 2)

      get "/projects/#{other.id}", headers: owner_headers

      expect(response).to have_http_status(:not_found)
    end
  end

  describe "POST /projects" do
    it "creates a project for the current owner" do
      expect {
        post "/projects", params: { project: { name: "Launch" } }, headers: owner_headers, as: :json
      }.to change(Project, :count).by(1)

      expect(response).to have_http_status(:created)
      expect(json).to include("name" => "Launch", "status" => "active", "owner_id" => 1)
    end

    it "ignores an owner_id in the body" do
      post "/projects", params: { project: { name: "Sneaky", owner_id: 2 } }, headers: owner_headers, as: :json

      expect(Project.last.owner_id).to eq(1)
    end

    it "returns 422 with errors for a duplicate name" do
      create(:project, name: "Launch")

      post "/projects", params: { project: { name: "Launch" } }, headers: owner_headers, as: :json

      expect(response).to have_http_status(:unprocessable_content)
      expect(json.dig("errors", "name")).to include("has already been taken")
    end

    # JSON bodies are wrapped under "project" by wrap_parameters, so send a form post
    # to reach params.expect with the key missing.
    it "returns 400 when the project key is missing" do
      post "/projects", params: { name: "Flat" }, headers: owner_headers

      expect(response).to have_http_status(:bad_request)
    end
  end

  describe "PATCH /projects/:id" do
    it "archives a project" do
      project = create(:project)

      patch "/projects/#{project.id}", params: { project: { status: "archived" } }, headers: owner_headers, as: :json

      expect(response).to have_http_status(:ok)
      expect(project.reload.status).to eq("archived")
    end

    it "rejects an unknown status" do
      project = create(:project)

      patch "/projects/#{project.id}", params: { project: { status: "deleted" } }, headers: owner_headers, as: :json

      expect(response).to have_http_status(:unprocessable_content)
    end
  end

  describe "DELETE /projects/:id" do
    it "deletes the owner's project" do
      project = create(:project)

      expect { delete "/projects/#{project.id}", headers: owner_headers }.to change(Project, :count).by(-1)
      expect(response).to have_http_status(:no_content)
    end
  end
end

require "spec_helper"
ENV["RAILS_ENV"] ||= "test"
require_relative "../config/environment"
abort("The Rails environment is running in production mode!") if Rails.env.production?
require "rspec/rails"

# Load the schema into the test database. Apps with a persistent test database use
# ActiveRecord::Migration.maintain_test_schema! instead.
ActiveRecord::Schema.verbose = false
load Rails.root.join("db/schema.rb")

RSpec.configure do |config|
  config.fixture_paths = [ Rails.root.join("spec/fixtures") ]
  config.use_transactional_fixtures = true
  config.infer_spec_type_from_file_location!
  config.filter_rails_from_backtrace!
  config.include FactoryBot::Syntax::Methods
end

RSpec.configure do |config|
  config.expect_with :rspec do |expectations|
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end
  config.mock_with :rspec do |mocks|
    mocks.verify_partial_doubles = true
  end
  config.shared_context_metadata_behavior = :apply_to_host_groups
  config.disable_monkey_patching!
  config.order = :random
  Kernel.srand config.seed
end

inherit_gem:
  rubocop-rails-omakase: rubocop.yml

plugins:
  - rubocop-rspec
  - rubocop-rspec_rails

AllCops:
  NewCops: enable
  Exclude:
    - "db/schema.rb"
    - "vendor/**/*"

RSpec/MultipleExpectations:
  Max: 3
RSpec/ExampleLength:
  Max: 12