active_admin_filter_extensions 1.0.0

data/spec/integration/required_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "rack/utils"
+
+# `required: true` promotes a filter's default from "applies to a bare request" to "applies
+# whenever THIS filter's key is absent" - the mandatory window every app hand-rolled as a
+# filter_defaults_apply? override. `skips_required: true` on a filter is the escape hatch: a search
+# that names a unique record gets exactly what it asked for.
+RSpec.describe "required: filters", type: :feature do
+  let!(:kept) do
+    Post.create!(title: "keep me", body: "keep body", status: "published",
+                 position: 20, published_date: Date.new(2026, 6, 1), starred: true)
+  end
+  let!(:dropped) do
+    Post.create!(title: "drop me", body: "drop body", status: "draft",
+                 position: 1, published_date: Date.new(2020, 1, 1), starred: false)
+  end
+
+  def query_of(url)
+    Rack::Utils.parse_nested_query(URI.parse(url).query.to_s)
+  end
+
+  it "applies beside the filters the request carries, in one hop" do
+    visit "/admin/required_posts?q%5Btitle_cont%5D=me"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("title_cont" => "me", "status_eq" => "published")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "counts a sibling predicate of its own filter as an answer" do
+    # Judged on the derived key alone, the default merged in beside the admin's own condition:
+    # two conditions on one column, both in the canonical URL, and the notice greeting it.
+    visit "/admin/required_sibling_posts?q%5Btitle_eq%5D=drop%20me"
+
+    expect(query_of(page.current_url)["q"]).to eq("title_eq" => "drop me")
+    expect(page).to have_content("drop me")
+    expect(page).to have_no_content("Showing kept titles by default")
+  end
+
+  it "still applies beside a predicate-less stem Ransack ignores" do
+    # q[title] is no condition at all - counting it would switch a mandatory window off with a
+    # key that searches nothing.
+    visit "/admin/required_sibling_posts?q%5Btitle%5D=drop"
+
+    expect(query_of(page.current_url)["q"]).to include("title_cont" => "keep")
+    expect(page).to have_content("keep me")
+  end
+
+  it "applies even to a blank filters-form submission" do
+    # A required window has no 'show me everything' escape - that is what required means.
+    visit "/admin/required_posts?commit=Filter"
+
+    expect(query_of(page.current_url)["q"]).to eq("status_eq" => "published")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "keeps the admin's own value for the required filter" do
+    visit "/admin/required_posts?q%5Bstatus_eq%5D=draft"
+
+    expect(query_of(page.current_url)["q"]).to eq("status_eq" => "draft")
+    expect(page).to have_content("drop me")
+    expect(page).to have_no_content("keep me")
+  end
+
+  it "steps aside for a search that names a unique record" do
+    visit "/admin/required_posts?q%5Bid_eq%5D=#{dropped.id}"
+
+    expect(URI.parse(page.current_url).query).to eq("q%5Bid_eq%5D=#{dropped.id}")
+    expect(page).to have_content("drop me")
+    expect(page).to have_no_content("keep me")
+  end
+
+  it "keeps required: away from the rendered input" do
+    # required: is also a Formtastic option: leaked through the merged-flat policy keys it
+    # would mark the sidebar input HTML-required and block blank form submits in the browser.
+    visit "/admin/required_posts"
+
+    expect(page).to have_css("#filters_sidebar_section")
+    expect(page).to have_no_css("#filters_sidebar_section [required]", visible: :all)
+  end
+
+  it "greets the imposed window with the notice" do
+    visit "/admin/required_posts?q%5Btitle_cont%5D=me"
+
+    expect(page).to have_content("Showing published posts by default")
+  end
+
+  describe "required: { if: }" do
+    it "imposes the window beside its trigger keys" do
+      visit "/admin/pinned_window_posts?q%5Btitle_cont%5D=me"
+
+      expect(query_of(page.current_url)["q"])
+        .to eq("title_cont" => "me", "status_eq" => "published")
+      expect(page).to have_no_content("drop me")
+    end
+
+    it "stays home beside any other filter" do
+      visit "/admin/pinned_window_posts?q%5Bposition_eq%5D=1"
+
+      expect(query_of(page.current_url)["q"]).to eq("position_eq" => "1")
+      expect(page).to have_content("drop me")
+    end
+
+    it "still applies as a plain default to the bare index" do
+      visit "/admin/pinned_window_posts"
+
+      expect(query_of(page.current_url)["q"]).to eq("status_eq" => "published")
+    end
+  end
+
+  it "raises for required: with an unknown option" do
+    expect { visit "/admin/banana_required_option_posts?q%5Btitle_cont%5D=x" }
+      .to raise_error(ArgumentError, /required:.*takes true or/m)
+  end
+
+  it "raises for required: with no default: to fall back on" do
+    expect { visit "/admin/required_banana_posts" }
+      .to raise_error(ArgumentError, /title_cont.*required.*no default/m)
+  end
+
+  it "counts any of the filter's own keys as answering the group" do
+    # An endless default fills only the gteq slot, but an upper-only request still answered
+    # THIS filter - injecting the default lower bound beside it would execute a pair the
+    # admin never meant.
+    visit "/admin/required_open_posts?q%5Bpublished_date_lteq%5D=2026-06-30"
+
+    expect(query_of(page.current_url)["q"]).to eq("published_date_lteq" => "2026-06-30")
+    expect(page).to have_content("keep me")
+    expect(page).to have_content("drop me")
+  end
+
+  it "treats an array of blanks as unanswered" do
+    # ?q[k][]= survives a naive blank check ([""].blank? is false) while Ransack discards
+    # the condition - an unanswered window wearing an answered-looking URL.
+    visit "/admin/required_posts?q%5Bstatus_eq%5D%5B%5D=&q%5Btitle_cont%5D=me"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("title_cont" => "me", "status_eq" => "published")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "treats blank-valued keys as unanswered" do
+    # ?q[status_eq]= must not defeat the window: a blank clobbering the default and Ransack
+    # then stripping the blank is a full-table scan wearing an answered-looking URL.
+    visit "/admin/required_posts?q%5Bstatus_eq%5D=&q%5Btitle_cont%5D=me"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("title_cont" => "me", "status_eq" => "published")
+    expect(page).to have_no_content("drop me")
+    expect(page).to have_content("Showing published posts by default")
+  end
+end

data/spec/integration/structural_keys_spec.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "rack/utils"
+
+# Ransack reads more than conditions out of q: `m` switches the combinator to OR, `g` nests
+# whole condition groups. No Active Admin filter form submits them, and every policy in this
+# gem reasons about flat condition keys - so a structural key is not an answer, it is a
+# bypass. They are stripped before anything reads the request.
+RSpec.describe "structural Ransack keys", type: :feature do
+  before do
+    Post.create!(title: "keep me", body: "keep body", status: "published",
+                 position: 20, published_date: Date.new(2026, 6, 1), starred: true)
+    Post.create!(title: "drop me", body: "drop body", status: "draft",
+                 position: 1, published_date: Date.new(2020, 1, 1), starred: false)
+  end
+
+  def query_of(url)
+    Rack::Utils.parse_nested_query(URI.parse(url).query.to_s)
+  end
+
+  it "strips q[m]=or instead of letting it turn a required window into a full scan" do
+    visit "/admin/window_posts?q%5Bm%5D=or" \
+          "&q%5Bpublished_date_gteq%5D=2026-05-01&q%5Bpublished_date_lteq%5D=2026-06-30"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "strips the long-form aliases Ransack also answers to" do
+    # `conditions` is `c` spelled out (as `sorts` is `s`) - the alias must not walk around
+    # the strip, least of all on the CSV, which gets no canonicalizing hop.
+    visit "/admin/string_posts.csv?q%5Bconditions%5D%5B0%5D%5Btitle_cont%5D=drop"
+
+    expect(page.body).to include("keep me")
+    expect(page.body).not_to include("drop me")
+  end
+
+  it "does not let a structural-only q suppress the defaults on CSV" do
+    # The HTML path would self-heal with a hop; the CSV runs filtering_params directly, and
+    # a q that holds nothing but structure is a bare request.
+    visit "/admin/string_posts.csv?q%5Bg%5D%5B0%5D%5Btitle_cont%5D=drop"
+
+    expect(page.body).to include("keep me")
+    expect(page.body).not_to include("drop me")
+  end
+
+  it "leaves a plain resource's own grouping alone" do
+    # q[g] is the standard Active Admin workaround for an OR search. On a resource that
+    # declares no extension there is no policy to bypass, and stripping it answered a narrowed
+    # export with the whole table.
+    visit "/admin/plain_posts.csv?q%5Bg%5D%5B0%5D%5Btitle_cont%5D=keep"
+
+    expect(page.body).to include("keep me")
+    expect(page.body).not_to include("drop me")
+  end
+
+  it "keeps a Ransack sort, which is no condition" do
+    # Stripped, q[s] was dropped from the search and erased from the canonical URL - the 302
+    # handed back a link that had lost the sort it was made for.
+    visit "/admin/posts?q%5Bs%5D=title+desc"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("s" => "title desc", "status_eq" => "published",
+             "published_date_gteq" => "2026-01-01")
+  end
+
+  it "strips q[g] groupings no value policy ever saw" do
+    visit "/admin/guarded_posts?q%5Bg%5D%5B0%5D%5Btitle_cont%5D=keep123"
+
+    expect(query_of(page.current_url)["q"]).to eq("title_cont" => "keep")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+end

data/spec/integration/window_spec.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "rack/utils"
+
+# `max_range:` and `min:` on a two-ended filter - the 90-day caps and retention floors three
+# of the four inventoried apps hand-rolled. A violation resets the PAIR: both bounds dropped,
+# one error flashed, the declared default refills.
+RSpec.describe "Window policies: max_range and min", type: :feature do
+  before do
+    Post.create!(title: "keep me", body: "keep body", status: "published",
+                 position: 20, published_date: Date.new(2026, 6, 1), starred: true)
+    Post.create!(title: "drop me", body: "drop body", status: "draft",
+                 position: 1, published_date: Date.new(2020, 1, 1), starred: false)
+  end
+
+  def query_of(url)
+    Rack::Utils.parse_nested_query(URI.parse(url).query.to_s)
+  end
+
+  def visit_window(gteq: nil, lteq: nil)
+    q = {}
+    q["q[published_date_gteq]"] = gteq if gteq
+    q["q[published_date_lteq]"] = lteq if lteq
+    visit "/admin/window_posts?#{Rack::Utils.build_query(q)}"
+  end
+
+  it "refuses a range wider than max_range and falls back to the default" do
+    visit_window(gteq: "2020-07-01", lteq: "2026-06-30")
+
+    expect(page).to have_content("allows a maximum date range of 90 days")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("Showing the default window")
+  end
+
+  it "refuses an inverted range" do
+    visit_window(gteq: "2026-06-10", lteq: "2026-06-01")
+
+    expect(page).to have_content("invalid date range value")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "keeps a range exactly as wide as the cap" do
+    # Pins > (not >=): under a gem regression both suites would stay green while the
+    # inclusive boundary silently flipped.
+    visit_window(gteq: "2026-03-01", lteq: "2026-05-30")
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-03-01", "published_date_lteq" => "2026-05-30")
+    expect(page).to have_no_content("maximum date range")
+  end
+
+  it "refuses an upper bound alone under a lone min: floor" do
+    # No lower bound means everything before the retention floor - refused and reset even
+    # when no max_range: is declared beside the floor.
+    visit "/admin/floor_posts?q%5Bpublished_date_lteq%5D=2026-06-30"
+
+    expect(page).to have_content("Published date: starts no earlier than 2020-06-01 (retention).")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "names a sub-day cap in the units it was declared in" do
+    # Divided into whole days, a cap shorter than one read "a maximum date range of 0 days".
+    visit "/admin/short_window_posts?q%5Bpublished_date_gteq%5D=2026-01-01" \
+          "&q%5Bpublished_date_lteq%5D=2026-06-30"
+
+    expect(page).to have_content("maximum date range of 6 hours")
+    expect(page).to have_no_content("of 0 days")
+  end
+
+  it "imposes nothing when a min: Proc resolves to nil" do
+    # An upper bound alone: both floor lookups are on this path, and nil.in_time_zone 500'd
+    # the request the floor was only meant to narrow.
+    visit "/admin/nil_floor_posts?q%5Bpublished_date_lteq%5D=2026-06-30"
+
+    expect(page).to have_no_content("cannot start before")
+    expect(page).to have_content("keep me")
+    expect(page).to have_content("drop me")
+  end
+
+  it "resets the whole pair when a value policy rejects one bound" do
+    # Half the admin's window completed from the default pair is a window nobody asked for
+    # and nothing validated - the CSV would execute it without the HTML's healing hop.
+    recent = (Date.current - 30).strftime("%Y-%m-%d")
+    visit "/admin/validated_window_posts.csv?q%5Bpublished_date_gteq%5D=#{recent}" \
+          "&q%5Bpublished_date_lteq%5D=2026-07-01X"
+
+    expect(page.body).to include("keep me")
+  end
+
+  it "raises for a default whose sanitizer widens it past its own cap" do
+    # The window is judged on what is actually stored - after the sanitizer, not before.
+    expect { visit "/admin/banana_sanitized_window_posts" }
+      .to raise_error(ArgumentError, /violates its own window policy/)
+  end
+
+  it "refuses a bound that is not a plain string" do
+    # ?q[..._gteq][]=date parses as a date via Array#to_s, then Ransack silently drops the
+    # wrapped condition - an in-cap-looking URL running the unbounded scan the cap refuses.
+    visit "/admin/window_posts?q%5Bpublished_date_gteq%5D%5B%5D=2026-06-01"
+
+    expect(page).to have_content("invalid date range value")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "refuses an unparseable bound" do
+    visit_window(gteq: "garbage", lteq: "2026-06-01")
+
+    expect(page).to have_content("invalid date range value")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "refuses an upper bound alone" do
+    # An upper bound alone is an infinitely wide window - the outage query the cap refuses.
+    visit_window(lteq: "2026-06-30")
+
+    expect(page).to have_content("allows a maximum date range of 90 days")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "refuses a bound before the min: floor, in the application's own words" do
+    # The message comes from the app's locale file overriding the gem key - the i18n seam.
+    visit_window(gteq: "2020-01-01", lteq: "2020-03-01")
+
+    expect(page).to have_content("Published date: starts no earlier than 2020-06-01 (retention).")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "treats a lower bound left open as unbounded" do
+    # An upper bound alone is an infinitely wide window - on the partitioned tables this
+    # feature targets, that is the outage query the cap exists to refuse.
+    visit_window(lteq: "2026-06-30")
+
+    expect(page).to have_content("allows a maximum date range of 90 days")
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+  end
+
+  it "measures an open upper bound against now" do
+    visit_window(gteq: "2020-07-01")
+
+    expect(page).to have_content("allows a maximum date range of 90 days")
+  end
+
+  it "lets a future lower bound with no upper bound through" do
+    # It selects a not-yet-written window - nothing to cap. (A hard loop in one of the apps
+    # came from measuring exactly this against Time.current.) Computed, not a literal: a
+    # hardcoded year goes red the day the clock catches up with it.
+    future = (Date.current + 60).strftime("%Y-%m-%d")
+    visit_window(gteq: future)
+
+    expect(page).to have_no_content("allows a maximum date range")
+    expect(query_of(page.current_url)["q"]).to eq("published_date_gteq" => future)
+    expect(page).to have_no_content("keep me")
+  end
+
+  it "keeps a range inside every limit untouched" do
+    visit_window(gteq: "2026-05-01", lteq: "2026-06-30")
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "published_date_lteq" => "2026-06-30")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("invalid date range")
+  end
+
+  it "raises for a beginless default under max_range:" do
+    # Unbounded below the cap: accepted, it would run the over-cap scan on every bare visit.
+    # The bound must land in the lteq slot to be judged.
+    expect { visit "/admin/banana_beginless_window_posts" }
+      .to raise_error(ArgumentError, /violates its own window policy/)
+  end
+
+  it "raises when the fallback default itself violates the policy" do
+    # Resetting into a default the policy would refuse again is a loop, not a fallback -
+    # that is a configuration error and says so loudly.
+    expect { visit "/admin/banana_window_posts?q%5Bpublished_date_gteq%5D=2020-07-01" }
+      .to raise_error(ArgumentError, /default.*violates its own/m)
+  end
+
+  describe "the floor across time zones" do
+    # Date#to_time speaks the SERVER zone while the bounds are parsed in Time.zone; with the
+    # two apart, a bound exactly on the floor date was spuriously rejected (or genuinely
+    # earlier ones silently passed, offset depending).
+    around do |example|
+      old_tz = ENV["TZ"]
+      ENV["TZ"] = "America/New_York"
+      example.run
+    ensure
+      ENV["TZ"] = old_tz
+    end
+
+    it "accepts a bound exactly on the floor whatever the server zone" do
+      visit_window(gteq: "2020-06-01", lteq: "2020-06-20")
+
+      expect(page).to have_no_content("cannot start before")
+      expect(query_of(page.current_url)["q"])
+        .to eq("published_date_gteq" => "2020-06-01", "published_date_lteq" => "2020-06-20")
+    end
+  end
+end

data/spec/integration/with_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "rack/utils"
+
+# `with:` - a cross-filter group: either every key or none. Half a pair is reset to the
+# declared defaults with a warning (the monthly-invoices year/month shape), whichever side
+# the half came from.
+RSpec.describe "with: filters", type: :feature do
+  before do
+    Post.create!(title: "keep me", body: "keep body", status: "published",
+                 position: 20, published_date: Date.new(2026, 6, 1), starred: true)
+    Post.create!(title: "drop me", body: "drop body", status: "draft",
+                 position: 1, published_date: Date.new(2020, 1, 1), starred: false)
+  end
+
+  def query_of(url)
+    Rack::Utils.parse_nested_query(URI.parse(url).query.to_s)
+  end
+
+  it "resets a half-answered group to the defaults, saying so" do
+    visit "/admin/paired_posts?q%5Bstatus_eq%5D=draft"
+
+    expect(page).to have_content("must be given together")
+    expect(query_of(page.current_url)["q"])
+      .to eq("status_eq" => "published", "starred_eq" => "true")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "names the filters without their predicates, whatever the predicate" do
+    # The old humanizer knew _eq/_in/_cont only; a _gteq pair flashed "Published date gteq".
+    visit "/admin/paired_date_posts?q%5Bpublished_date_gteq%5D=2026-01-01"
+
+    expect(page).to have_content("Position and Published date filters must be given together")
+  end
+
+  it "trips from the side that declared nothing" do
+    # PairedDatePost declares with: only on published_date; the partner must trip the
+    # same group.
+    visit "/admin/paired_date_posts?q%5Bposition_eq%5D=1"
+
+    expect(page).to have_content("must be given together")
+    expect(URI.parse(page.current_url).query).to be_nil
+  end
+
+  it "warns once for mirrored declarations" do
+    # PairedPost declares with: on both members - the two declarations are one group.
+    visit "/admin/paired_posts?q%5Bstatus_eq%5D=draft"
+
+    expect(page).to have_css(".flash_warning", count: 1)
+  end
+
+  it "does not count a blank-array partner as answered" do
+    # q[partner][]= survives a raw present? check while normalization drops it - on the CSV,
+    # which gets no canonicalizing hop, half the group would execute silently.
+    visit "/admin/paired_posts.csv?q%5Bstatus_eq%5D=draft&q%5Bstarred_eq%5D%5B%5D="
+
+    expect(page.body).to include("keep me")
+    expect(page.body).not_to include("drop me")
+  end
+
+  it "counts a two-ended member answered by either bound" do
+    # Each bound counted as a group key of its own, so one date bound beside the partner read
+    # as two of three: both reset, and with no defaults the whole table rendered - the scan the
+    # guard exists to prevent.
+    visit "/admin/paired_date_posts?q%5Bpublished_date_gteq%5D=2026-01-01&q%5Bposition_eq%5D=20"
+
+    expect(page).to have_no_content("must be given together")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "counts a two-ended member whose default fills only one end" do
+    # Same arithmetic on the fallback side: the half-open default answered one of three keys
+    # and read as a half-declared group.
+    visit "/admin/open_paired_posts"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("published_date_gteq" => "2026-05-01", "position_eq" => "20")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "keeps separately declared partners on one attribute distinct" do
+    # Two single-ended filters are two members, not one two-ended input: grouping them by the
+    # stripped attribute made half an answer pass as a whole group.
+    visit "/admin/split_pair_posts?q%5Bposition_gteq%5D=10"
+
+    expect(page).to have_content("must be given together")
+    expect(page).to have_content("keep me")
+    expect(page).to have_content("drop me")
+  end
+
+  it "lets both halves of a split pair through" do
+    visit "/admin/split_pair_posts?q%5Bposition_gteq%5D=10&q%5Bposition_lteq%5D=30"
+
+    expect(page).to have_no_content("must be given together")
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "raises when only one half of a split pair declares a default" do
+    expect { visit "/admin/banana_split_pair_posts" }
+      .to raise_error(ArgumentError, /answer the whole\s+group or none/m)
+  end
+
+  it "lets a fully-answered group through" do
+    visit "/admin/paired_posts?q%5Bstatus_eq%5D=draft&q%5Bstarred_eq%5D=false"
+
+    expect(page).to have_no_content("must be given together")
+    expect(page).to have_content("drop me")
+    expect(page).to have_no_content("keep me")
+  end
+
+  it "treats overlapping groups as one question" do
+    # [title,status] and [status,starred] share status: answering title+status must not
+    # pass the first group and then have the second reset status out from under it - on the
+    # CSV, which gets no second chance.
+    visit "/admin/chained_pair_posts.csv?q%5Btitle_cont%5D=keep&q%5Bstatus_eq%5D=published"
+
+    expect(page.body).to include("keep me")
+    expect(page.body).to include("drop me")
+  end
+
+  it "pulls the partner's default along with a required refill" do
+    # status is required-with-default and with: starred; starred defaults to false. The
+    # refill must carry both, or the search runs the half-group enforcement never saw.
+    visit "/admin/required_pair_posts.csv?q%5Btitle_cont%5D=keep"
+
+    expect(page.body).not_to include("keep me")
+    expect(page.body).not_to include("drop me")
+  end
+
+  it "carries the whole group through the redirect on a required refill" do
+    visit "/admin/required_pair_posts?q%5Btitle_cont%5D=keep"
+
+    expect(query_of(page.current_url)["q"])
+      .to eq("title_cont" => "keep", "status_eq" => "published", "starred_eq" => "false")
+  end
+
+  it "imposes nothing when a member's default resolves to nil" do
+    # A nil Proc result is how a per-admin default opts out. Read as a missing declaration it
+    # raised the half-group config error on every bare visit, per admin.
+    visit "/admin/nil_paired_posts"
+
+    expect(page).to have_no_content("must be given together")
+    expect(URI.parse(page.current_url).query).to be_nil
+    expect(page).to have_content("keep me")
+    expect(page).to have_content("drop me")
+  end
+
+  it "says nothing about a default slice the suppressed group is not showing" do
+    # The group imposed nothing, so the collection is unfiltered - and the notice announced a
+    # default slice over the whole table, which is the notice lying about the page.
+    visit "/admin/nil_paired_posts"
+
+    expect(page).to have_no_content("Showing published starred posts by default")
+    expect(page).to have_content("keep me")
+    expect(page).to have_content("drop me")
+  end
+
+  it "raises when defaults answer only half the group" do
+    # The fallback is held to the same all-or-none contract the enforcement imposes.
+    expect { visit "/admin/banana_half_paired_posts" }
+      .to raise_error(ArgumentError, /answer the whole\s+group or none/m)
+  end
+
+  it "says nothing on a bare visit" do
+    visit "/admin/paired_posts"
+
+    expect(page).to have_no_content("must be given together")
+    expect(page).to have_content("keep me")
+  end
+end

data/spec/rails_helper.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Boots the generated sample app. Only the integration specs need this - the unit specs run
+# against a stand-in controller and stay in spec_helper.
+
+$LOAD_PATH.unshift(File.expand_path("support", __dir__))
+
+ENV["BUNDLE_GEMFILE"] = File.expand_path("../Gemfile", __dir__)
+require "bundler"
+Bundler.setup
+
+ENV["RAILS_ENV"] = "test"
+require "rails"
+ENV["RAILS"] = Rails.version
+ENV["RAILS_ROOT"] = File.expand_path("rails/rails-#{ENV['RAILS']}", __dir__)
+
+unless File.exist?(ENV["RAILS_ROOT"])
+  # A generation that dies midway leaves a partial app the File.exist? guard would then skip
+  # forever - fail the run instead of limping into it.
+  system("rake setup") ||
+    abort("rake setup failed - remove #{ENV['RAILS_ROOT']} before retrying")
+end
+
+# An app generated from an older template would silently pass against resources the template
+# no longer declares - refuse it instead.
+require "digest"
+template_digest = Digest::SHA256.file(File.expand_path("support/rails_template.rb", __dir__)).hexdigest
+stamp = File.join(ENV["RAILS_ROOT"], ".rails_template_digest")
+unless File.exist?(stamp) && File.read(stamp).strip == template_digest
+  abort "#{ENV['RAILS_ROOT']} was generated from an older rails_template.rb - "         "remove it (git clean -fdx spec/rails) and rerun, rake setup regenerates it"
+end
+
+require "active_model"
+# Required before Active Admin so that Ransack loads correctly.
+require "active_record"
+require "action_view"
+require "active_admin"
+ActiveAdmin.application.load_paths = ["#{ENV['RAILS_ROOT']}/app/admin"]
+require "#{ENV['RAILS_ROOT']}/config/environment"
+
+# Specs are about filters, not about signing in.
+ActiveAdmin.application.authentication_method = false
+ActiveAdmin.application.current_user_method = false
+
+require "rspec/rails"
+require "capybara/rails"
+require "capybara/rspec"
+require "database_cleaner/active_record"
+require "capybara_driver"
+
+RSpec.configure do |config|
+  config.use_transactional_fixtures = false
+
+  config.before(:suite) do
+    ActiveRecord::Migration.maintain_test_schema!
+    DatabaseCleaner.strategy = :truncation
+    DatabaseCleaner.clean_with(:truncation)
+  end
+
+  config.before { DatabaseCleaner.start }
+  config.after { DatabaseCleaner.clean }
+end