mensa 0.6.16 → 0.6.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a88070a879c44aa30934fd328a74c21546c2517999731ad033dc10022d2a4ee
-  data.tar.gz: 3940bc3931ce9f0a0aad748c378cbd7c3231616cedea960f7c24ab7bdc974cf2
+  metadata.gz: a9bbb252521ea00a7d6197e9ae12208d121ec069652b45b729095609a596bda2
+  data.tar.gz: 92345f45e5b1336f1e101c2c64d9736c58637cb9792c333cc21f4620dadabf94
 SHA512:
-  metadata.gz: 77fe83cd050e611f24086db47cd0a0f9330459289390df37361a97f82950819a0b22a0d6573a094be0cf4d7f6455624ccf08c44fd4f7d8c1c4398077df3fb192
-  data.tar.gz: a5485bbe47e59950753d270fde0ffc7618ec760837b3c2f435fa4b9f798c81822e514dab1e9688a090b2d31cc13929b2ecdd4fe3038ec57db6581eecb61b18aa
+  metadata.gz: 2b97589e71ee52505369eb9cac3af5e49672c8af62d076d2f17465ea76b2c556ca2c5adbede3af5ad850db502bd47271e031c96a5292eb2ef191818e24e60435
+  data.tar.gz: ba31a706fa85f69d30a1b4bfcb17d2c6674df561daf8379341b3f7dc31d21bd10ecc94fc36192f0f2302e602556898c72d9b3d203e330f2a60494c3741b004f2

data/.shipkit.yml

@@ -1,2 +1,2 @@
 ---
-previous_version: 0.6.15
+previous_version: 0.6.17

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+- `Mensa::Verifier` checks a table against the database: scope, column SQL,
+  sorting, rendering, filters, search, CSV export, grouping/aggregates and
+  views. Run it with `bin/rails "mensa:verify[table]"` / `mensa:verify_all`,
+  or from tests after `require "mensa/testing"` with
+  `assert_mensa_table_valid` or `be_a_valid_mensa_table`. Set defaults for
+  its context with `config.verifier_context`.
+- `Mensa::ExportJob.write_csv(io, table, rows)` writes a table's CSV export and
+  `Mensa::ExportJob#generate_file(export)` generates an export's file without
+  saving it.
+- Exports of tables with a `csv` render block no longer fail: the export job
+  renders with a view context of `config.base_controller`
+  (`Mensa.offline_view_context`).
+- Row actions without an `icon` show their title instead of raising.
+- An unknown helper in a render block raises `NoMethodError` instead of
+  `SystemStackError`. Only the app's `*_path`/`*_url` helpers are forwarded to
+  `main_app`.
+- Search leaves out columns with a `having` filter (aggregates), which broke the
+  query.
+- `is_duplicate` works for columns with a `having` filter.
+
 ## 0.6.16
 
 - Custom filter `scope` blocks can take the operator as a second argument,

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mensa (0.6.15)
+    mensa (0.6.17)
       csv
       importmap-rails
       pagy (>= 43)

data/README.md

@@ -320,6 +320,94 @@ If you're just using cron, you can add the following to your crontab:
 0 0 * * * rails runner "Mensa::RecurringExportsJob.perform_later"
 ```
 
+### Verifying tables
+
+`Mensa::Verifier` checks that everything a table configures works against your
+real database, using the same code paths as requests do:
+
+- **Loads**: the table builds, its SQL builds and the first two pages load. A default
+  `order` or `column_order` naming an unknown column fails.
+- **Columns**: every column (internal ones too) can be selected and, when sortable,
+  sorted both ways. Its html and csv renders run for a few records. Columns hidden
+  by a `visible` lambda are reported as skipped.
+- **Filters**: every filterable column is applied with each of its operators, using
+  the first values of its `collection` or a value that fits the column's type, and
+  the filter pill's text is built. `is_current` is skipped when `Current` has no
+  value for the column.
+- **Search**: basic and fuzzy search (when `pg_trgm` is enabled) for a word taken
+  from the records.
+- **Rendering**: the `table` helper as your views call it, the rows and filter pills
+  as Mensa's controller renders them, the row link and every row action.
+- **Exports**: `Mensa::ExportJob` generates the first page of the export, also for
+  each view and as a password protected zip. It needs the expected headers
+  (skipped for `exportable false`).
+- **Grouping**: every groupable column and every aggregate, rendered with their
+  group headers. A `group_by` or `aggregates` naming a column that doesn't allow
+  it fails, because Mensa would silently ignore it.
+- **Views**: system views load, render and only refer to existing columns. With
+  custom views enabled, saved views load too.
+
+Each check runs on its own, so one failure doesn't hide the others. Everything runs
+in a read-only transaction that is rolled back, with small limits, so it is safe to
+run against staging. It never writes.
+
+#### From rake
+
+```sh
+bin/rails "mensa:verify[inventories]"   # or InventoriesTable
+bin/rails mensa:verify_all              # every table in app/tables
+```
+
+The tasks print a report (✓ passed, ✗ failed with the error and SQL, - skipped) and
+exit non-zero when a check failed. Classes and modules that don't descend from
+`Mensa::Base` (e.g. helpers in `app/tables`) are reported as skipped.
+
+#### From tests
+
+```ruby
+# test/test_helper.rb or spec/rails_helper.rb
+require "mensa/testing"
+
+# Minitest
+assert_mensa_table_valid InventoriesTable, user: users(:admin)
+
+# RSpec
+expect(InventoriesTable).to be_a_valid_mensa_table(user: admin)
+
+# Plain Ruby
+result = Mensa::Verifier.new(InventoriesTable, user: admin).call
+result.success?  # => true
+result.failures  # => [#<struct Mensa::Verifier::Check section: :filters, subject: :status, ...>]
+puts result      # the report, also the failure message of the helpers
+```
+
+#### Context
+
+Tables often depend on the request: `Current.user`, policy scopes, or the table's
+params. Give the verifier that context:
+
+- `user:` and `account:` set `Current.user` and `Current.account` while verifying.
+- `context: {organization: org}` sets any other `Current` attributes.
+- `params: {customer_id: 1}` sets the table's params (see "Table params").
+- A block is called with the verifier before the checks, for any other setup.
+
+Html render blocks run in a view context of your `ApplicationController` (see
+`config.base_controller`), so url helpers and your helpers work.
+
+From rake, set `USER_ID=` (finds a `User`), `ACCOUNT_ID=` (finds an `Account`) and
+`PARAMS='{"customer_id":1}'` (JSON), or configure defaults for every table in
+your initializer. The options you pass yourself override these defaults:
+
+```ruby
+Mensa.setup do |config|
+  config.verifier_context = ->(table_class) {
+    options = {user: User.find_by!(email: "admin@example.com")}
+    options[:params] = {customer_id: Customer.first.id} if table_class == CustomerUsersTable
+    options
+  }
+end
+```
+
 ## Contributing
 
 ```

data/app/components/mensa/row_action/component.html.erb

@@ -4,7 +4,6 @@
     <% if icon = action.icon(row.record) %>
       <i class="fa <%= icon %>"></i>
     <% else %>
-      <%= name %>
+      <%= action.title %>
     <% end %>
-  <% end %>
-<% end %>
+  <% end %>

data/app/helpers/mensa/application_helper.rb

@@ -6,16 +6,21 @@ module Mensa
       render(component)
     end
 
+    # The app's url helpers, also inside Mensa's engine views
     def respond_to_missing?(method, include_private = false)
-      if method.to_s.ends_with?("_url") || method.to_s.ends_with?("_path") && main_app.respond_to?(method)
-        true
-      else
-        super
-      end
+      main_app_url_helper?(method) || super
     end
 
     def method_missing(method, *args, **kwargs, &block)
-      main_app.send(method, *args, **kwargs, &block)
+      return super unless main_app_url_helper?(method)
+
+      main_app.public_send(method, *args, **kwargs, &block)
+    end
+
+    private
+
+    def main_app_url_helper?(method)
+      method.to_s.end_with?("_url", "_path") && main_app.respond_to?(method)
     end
   end
 end

data/app/jobs/mensa/export_job.rb

@@ -9,20 +9,30 @@ module Mensa
   class ExportJob < ApplicationJob
     queue_as :default
 
+    # Writes the CSV for +rows+ (Mensa::Row) of +table+ to +io+: a header row
+    # with the display column names, then one line per row.
+    def self.write_csv(io, table, rows)
+      csv = CSV.new(io)
+      csv << table.display_columns.map(&:name)
+      rows.each do |row|
+        csv << table.display_columns.map { |column| Mensa::Cell.new(row: row, column: column).render(:csv) }
+      end
+      csv.flush
+      io
+    end
+
     def perform(export)
       return unless export
 
       export.update(status: "processing")
       Mensa.config.run_callback(:export_started, export)
 
-      table = build_table(export)
-      unless table.exportable?
+      tempfile, filename, content_type = generate_file(export)
+      unless tempfile
         finalize(export, status: "failed")
         return
       end
 
-      tempfile, filename, content_type = generate(table, export)
-
       export.asset.purge if export.asset.attached?
       export.asset.attach(io: tempfile, filename: filename, content_type: content_type)
       finalize(export, status: "completed", filename: filename)
@@ -36,6 +46,16 @@ module Mensa
       tempfile&.close!
     end
 
+    # Builds the table for +export+ and generates its file. Returns
+    # [tempfile, filename, content_type], or nil when the table isn't
+    # exportable. Doesn't touch the export's record or asset.
+    def generate_file(export)
+      table = build_table(export)
+      return unless table.exportable?
+
+      generate(table, export)
+    end
+
     private
 
     # Rebuilds the table the export was requested for, layering the view
@@ -54,6 +74,8 @@ module Mensa
       table = Mensa.for_name(export.table_name, config)
       table.request = ActionDispatch::Request.new({})
       table.request.set_header("action_dispatch.request.query_parameters", {"page" => config[:page]})
+      # Render blocks (e.g. csv) run in a view context
+      table.original_view_context = Mensa.offline_view_context
       table
     end
 
@@ -78,12 +100,8 @@ module Mensa
       # with programmatic consumers.
       tempfile.write("\uFEFF") if export.format == "csv_excel"
 
-      csv = CSV.new(tempfile)
-      csv << table.display_columns.map(&:name)
-      export_rows(table, export).each do |row|
-        csv << table.display_columns.map { |column| Mensa::Cell.new(row: row, column: column).render(:csv) }
-      end
-      csv.close
+      self.class.write_csv(tempfile, table, export_rows(table, export))
+      tempfile.close
       tempfile.open
       tempfile.binmode
       tempfile.rewind

data/app/tables/mensa/filter.rb

@@ -119,6 +119,7 @@ module Mensa
       when :isnt_empty
         (column.type == :string) ? "#{col} IS NOT NULL AND #{col} != ''" : "#{col} IS NOT NULL"
       when :is_current
+        hash[:value] = Current.public_send(column.name)
         "#{col} = :value"
       when :matches
         "#{col} LIKE :value"
@@ -210,6 +211,7 @@ module Mensa
     def apply_duplicate_filter(record_scope)
       column_sql = column.attribute_for_condition.to_s
       base_scope = record_scope.except(:select, :order, :limit, :offset)
+      return apply_duplicate_having_filter(record_scope, base_scope, column_sql) if having?
 
       duplicate_values_scope = base_scope
         .where("#{column_sql} IS NOT NULL")
@@ -222,6 +224,19 @@ module Mensa
         .where("#{column_sql} IN (#{duplicate_values_scope.to_sql})")
     end
 
+    # Aggregates are only known per group, so the duplicate values come from
+    # a subquery of the grouped rows and are compared in the HAVING
+    def apply_duplicate_having_filter(record_scope, base_scope, column_sql)
+      duplicate_values_scope = base_scope.model.unscoped
+        .from(base_scope.select(Arel.sql("#{column_sql} AS mensa_duplicate_value")), :mensa_values)
+        .where("mensa_values.mensa_duplicate_value IS NOT NULL")
+        .group("mensa_values.mensa_duplicate_value")
+        .having("COUNT(*) > 1")
+        .select("mensa_values.mensa_duplicate_value")
+
+      record_scope.having("#{column_sql} IN (#{duplicate_values_scope.to_sql})")
+    end
+
     # Unused at the moment
     def normalize(query)
       query

data/app/tables/mensa/search.rb

@@ -10,7 +10,8 @@ module Mensa
       return record_scope if query.blank?
       return record_scope unless record_scope.is_a?(ActiveRecord::Relation)
 
-      searchable_attributes = columns.filter_map(&:attribute_for_condition).uniq
+      # Aggregates (filter having) can't be in a WHERE
+      searchable_attributes = columns.reject { |column| column.filter&.having? }.filter_map(&:attribute_for_condition).uniq
       return record_scope if searchable_attributes.empty?
 
       @search_order_clause = nil

data/lib/generators/mensa/templates/config/initializers/mensa.rb

@@ -7,6 +7,10 @@ Mensa.setup do |config|
     end
   }
 
+  # Context for `rails mensa:verify` and the test helpers (user:, account:,
+  # context:, params:)
+  # config.verifier_context = ->(table_class) { {user: User.find_by!(email: "admin@example.com")} }
+
   # Override icons in use
   config.icons = {
     add_filter_trigger: "fa-solid fa-circle-plus",

data/lib/mensa/configuration.rb

@@ -144,6 +144,12 @@ module Mensa
     option :row_actions_position, default: :back
     # It's either :basic or :fuzzy, for fuzzy search you need to have `pg_trgm` extension installed
     option :search, default: :basic
+    # Default options for Mensa::Verifier (and so `rails mensa:verify`), called
+    # with the table class. Return a hash with any of user:, account:,
+    # context: (Current attributes) and params:, e.g.
+    #
+    #   config.verifier_context = ->(table_class) { {user: User.find_by!(email: "admin@example.com")} }
+    option :verifier_context, default: nil
 
     def initialize
       set_defaults!

data/lib/mensa/testing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "mensa/verifier"
+
+module Mensa
+  # Test helpers on top of Mensa::Verifier, opt in with `require "mensa/testing"`.
+  #
+  #   assert_mensa_table_valid UsersTable, user: users(:admin)        # Minitest
+  #   expect(UsersTable).to be_a_valid_mensa_table(user: admin)        # RSpec
+  #
+  # Both take the verifier's options (user:, account:, context:, params:)
+  # and fail with its report.
+  module Testing
+    module Assertions
+      def assert_mensa_table_valid(table, message = nil, **options, &setup)
+        result = Mensa::Verifier.new(table, **options, &setup).call
+        assert result.success?, -> { [message, result.to_s].compact.join("\n\n") }
+        result
+      end
+    end
+
+    class ValidTableMatcher
+      attr_reader :result
+
+      def initialize(**options, &setup)
+        @options = options
+        @setup = setup
+      end
+
+      def matches?(table)
+        @result = Mensa::Verifier.new(table, **@options, &@setup).call
+        @result.success?
+      end
+
+      def failure_message
+        result.to_s
+      end
+
+      def failure_message_when_negated
+        "expected #{result.table_class} not to be a valid Mensa table, but all its checks passed"
+      end
+
+      def description
+        "be a valid Mensa table"
+      end
+    end
+
+    module Matchers
+      def be_a_valid_mensa_table(**options, &setup)
+        ValidTableMatcher.new(**options, &setup)
+      end
+    end
+  end
+end
+
+if defined?(Minitest::Test)
+  Minitest::Test.include(Mensa::Testing::Assertions)
+else
+  ActiveSupport.on_load(:active_support_test_case) { include Mensa::Testing::Assertions }
+end
+
+RSpec.configure { |config| config.include(Mensa::Testing::Matchers) } if defined?(RSpec) && RSpec.respond_to?(:configure)

data/lib/mensa/verifier/result.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Mensa
+  class Verifier
+    # One verified aspect of a table, e.g. sorting a column descending.
+    #
+    # +section+ groups checks in the report (:loads, :columns, :filters, ...),
+    # +subject+ is the column, filter or view it relates to.
+    Check = Struct.new(:section, :subject, :name, :status, :message, :sql, :error) do
+      def passed?
+        status == :passed
+      end
+
+      def failed?
+        status == :failed
+      end
+
+      def skipped?
+        status == :skipped
+      end
+
+      def label
+        [subject, name].compact.join(": ")
+      end
+    end
+
+    class Result
+      SECTIONS = {
+        loads: "Loads",
+        columns: "Columns",
+        filters: "Filters",
+        search: "Search",
+        render: "Rendering",
+        exports: "Exports",
+        grouping: "Grouping",
+        views: "Views"
+      }.freeze
+
+      SYMBOLS = {passed: "✓", failed: "✗", skipped: "-"}.freeze
+
+      attr_reader :table_class, :checks
+
+      def initialize(table_class)
+        @table_class = table_class
+        @checks = []
+      end
+
+      # False for a class that isn't a Mensa::Base subclass, which is skipped
+      def mensa_table?
+        table_class.is_a?(Class) && table_class < Mensa::Base
+      end
+
+      def success?
+        failures.empty?
+      end
+
+      def failures
+        checks.select(&:failed?)
+      end
+
+      def passes
+        checks.select(&:passed?)
+      end
+
+      def skips
+        checks.select(&:skipped?)
+      end
+
+      def summary
+        "#{passes.size} passed, #{failures.size} failed, #{skips.size} skipped"
+      end
+
+      def to_s
+        return "#{table_class}\n  - skipped: #{checks.first&.message}" unless mensa_table?
+
+        lines = [(table_class.name || table_class).to_s]
+
+        checks.group_by(&:section).each do |section, section_checks|
+          lines << "  #{SECTIONS.fetch(section, section.to_s.humanize)}"
+          section_checks.each do |check|
+            lines << "    #{SYMBOLS[check.status]} #{check.label}#{" (skipped: #{check.message})" if check.skipped?}"
+            next unless check.failed?
+
+            check.message.to_s.each_line { |line| lines << "        #{line.chomp}" }
+            lines << "        SQL: #{check.sql}" if check.sql.present?
+          end
+        end
+
+        lines << ""
+        lines << "#{success? ? "OK" : "FAILED"}: #{summary}"
+        lines.join("\n")
+      end
+      alias_method :report, :to_s
+
+      def inspect
+        "#<#{self.class.name} #{table_class} #{summary}>"
+      end
+    end
+  end
+end

data/lib/mensa/verifier.rb

@@ -0,0 +1,620 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+require "stringio"
+require "mensa/verifier/result"
+
+module Mensa
+  # Checks that everything a table configures works against the real database:
+  # its scope, every column's SQL, sorting, rendering, filters, search, the CSV
+  # export, grouping/aggregates and its views.
+  #
+  #   result = Mensa::Verifier.new(UsersTable, user: User.first).call
+  #   result.success? # => true
+  #   puts result     # per-check report
+  #
+  # Checks go through the same code paths as requests do (filtered_scope,
+  # ordered_scope, Mensa::Cell, Mensa::ExportJob.write_csv, ...). Everything
+  # runs in a read-only transaction that is rolled back, and every check in its
+  # own savepoint so one failing query doesn't stop the others.
+  #
+  # Tables often depend on request context, give it with user:, account: and
+  # context: (all set on Current while verifying), params: (the table's
+  # params) or a block, which is called with the verifier before the checks.
+  # Mensa.config.verifier_context supplies defaults for these.
+  class Verifier
+    # Records loaded for record-level checks, and per query
+    SAMPLE_SIZE = 5
+
+    class Skip < StandardError; end
+
+    # A problem the verifier found itself, reported without the class name
+    class Failure < StandardError; end
+
+    attr_reader :table_class, :user, :account, :context, :params, :result
+
+    class << self
+      # Accepts a table class, its name (e.g. "UsersTable") or Mensa's table
+      # name (e.g. "users", "admin_users").
+      def resolve_table_class(table)
+        return table if table.is_a?(Module)
+
+        name = table.to_s
+        (name.safe_constantize if name.match?(/\A[A-Z]/)) || Mensa.class_for_name(name.underscore.delete_suffix("_table"))
+      end
+
+      # The classes and modules defined by the files under +root+ (the app's
+      # app/tables), including any that aren't Mensa tables, which are
+      # reported as skipped.
+      def table_classes(root = Rails.root.join("app/tables"))
+        loader = Rails.autoloaders.main
+
+        Dir[File.join(root.to_s, "**/*.rb")].filter_map { |path|
+          loader.cpath_expected_at(path)&.safe_constantize
+        }.uniq.sort_by(&:name)
+      end
+
+      # Verifies the tables (all under app/tables when none are given), prints
+      # their reports to +io+ and returns true when all of them passed.
+      # Context comes from USER_ID, ACCOUNT_ID and PARAMS (JSON) in +env+, used
+      # by the mensa:verify rake tasks.
+      def run(tables = nil, env: ENV, io: $stdout)
+        classes = tables.present? ? Array(tables).map { |table| resolve_table_class(table) } : table_classes
+        options = options_from_env(env)
+
+        results = classes.map do |klass|
+          new(klass, **options).call.tap { |result| io.puts(result, "") }
+        end
+
+        tables, others = results.partition(&:mensa_table?)
+        if results.size > 1
+          io.puts ["#{tables.count(&:success?)}/#{tables.size} tables passed", ("#{others.size} skipped, not a Mensa::Base subclass" if others.any?)].compact.join(", ")
+        end
+        results.all?(&:success?)
+      end
+
+      def options_from_env(env)
+        options = {}
+        options[:user] = "User".constantize.find(env["USER_ID"]) if env["USER_ID"].present?
+        options[:account] = "Account".constantize.find(env["ACCOUNT_ID"]) if env["ACCOUNT_ID"].present?
+        options[:params] = JSON.parse(env["PARAMS"]) if env["PARAMS"].present?
+        options
+      end
+    end
+
+    def initialize(table, user: nil, account: nil, context: {}, params: nil, view_context: nil, &setup)
+      @table_class = self.class.resolve_table_class(table)
+      defaults = default_options
+      @user = user || defaults[:user]
+      @account = account || defaults[:account]
+      @context = (defaults[:context] || {}).merge(context || {})
+      @params = params || defaults[:params] || {}
+      @view_context = view_context
+      @setup = setup
+      @result = Result.new(@table_class)
+    end
+
+    def call
+      return result if @called
+
+      @called = true
+      unless result.mensa_table?
+        result.checks << Check.new(section: :loads, name: "Mensa table", status: :skipped, message: "#{table_class} does not descend from Mensa::Base")
+        return result
+      end
+
+      read_only_transaction do
+        with_current_attributes do
+          @setup&.call(self)
+          run_checks
+        end
+      end
+      result
+    end
+
+    # Mensa's name for the table, as used in its routes and saved views
+    def table_name
+      @table_name ||= table_class.name.underscore.delete_suffix("_table").tr("/", "_")
+    end
+
+    # Builds the table like a request would, with the request config on top
+    def build_table(config = {})
+      table = table_class.new({params: params}.merge(config))
+      table.name = table_name
+      table.request = request
+      table.original_view_context = view_context
+      table
+    end
+
+    def request
+      @request ||= ActionDispatch::Request.new(Rack::MockRequest.env_for("http://#{default_host}/"))
+    end
+
+    # A view context of the app's base controller, so html render blocks have
+    # the app's helpers and url helpers.
+    def view_context
+      @view_context ||= Mensa.offline_view_context(request)
+    end
+
+    private
+
+    def default_options
+      options = Mensa.config.verifier_context&.call(table_class)
+      options.is_a?(Hash) ? options.symbolize_keys : {}
+    end
+
+    def default_host
+      Rails.application.routes.default_url_options[:host] || "localhost"
+    end
+
+    def run_checks
+      @table = check(:loads, nil, "build table") { build_table }
+      unless @table
+        result.checks << Check.new(section: :loads, name: "remaining checks", status: :skipped, message: "the table could not be built")
+        return
+      end
+
+      # A table of its own, a relation can't be counted after its to_sql
+      check(:loads, nil, "build SQL") { |c| c.sql = build_table.selected_scope.to_sql }
+      @rows = check(:loads, nil, "load first page") { @table.rows }
+      verify_second_page
+      verify_defaults
+
+      verify_columns
+      verify_filters
+      verify_search
+      verify_rendering
+      verify_exports
+      verify_grouping
+      verify_views
+    end
+
+    # Runs the block as one check in its own savepoint and records the
+    # outcome. Returns the block's value, nil when the check didn't pass.
+    # Quiet checks are only reported when they fail.
+    def check(section, subject, name, quiet: false)
+      c = Check.new(section: section, subject: subject, name: name)
+      value = nil
+      savepoint { value = yield(c) }
+      c.status = :passed
+      value
+    rescue Skip => e
+      c.status = :skipped
+      c.message = e.message
+      nil
+    rescue StandardError, NotImplementedError => e
+      c.status = :failed
+      c.error = e
+      c.message = e.is_a?(Failure) ? e.message : "#{e.class}: #{e.message}"
+      c.sql = e.sql if e.respond_to?(:sql) && e.sql.present?
+      nil
+    ensure
+      result.checks << c unless quiet && c.passed?
+    end
+
+    def skip!(reason)
+      raise Skip, reason
+    end
+
+    def savepoint
+      ActiveRecord::Base.transaction(requires_new: true) do
+        yield
+        raise ActiveRecord::Rollback
+      end
+    end
+
+    # Record-level checks need loaded records
+    def sample_rows!
+      skip!("records could not be loaded") if @rows.nil?
+      skip!("no records") if @rows.empty?
+
+      @rows.first(SAMPLE_SIZE)
+    end
+
+    def verify_second_page
+      check(:loads, nil, "load page 2") do
+        skip!("records could not be loaded") if @rows.nil?
+        skip!("only one page") if @table.pagy_details.pages < 2
+
+        table = build_table
+        table.request = ActionDispatch::Request.new(Rack::MockRequest.env_for("http://#{default_host}/?page=2"))
+        table.rows
+      end
+    end
+
+    # Defaults on the table itself that Mensa would silently ignore
+    def verify_defaults
+      config = @table.config.slice(:order, :column_order).compact_blank
+      return if config.empty?
+
+      check(:loads, nil, "configured #{config.keys.join(", ")}") do
+        problems = config_problems(config)
+        raise Failure, problems.join("\n") if problems.any?
+      end
+    end
+
+    # Columns
+
+    def verify_columns
+      @table.columns.each do |column|
+        verify_column_select(column)
+        verify_column_sort(column) if column.sortable? && !column.internal?
+        verify_column_render(column) unless column.internal?
+      end
+    end
+
+    def verify_column_select(column)
+      check(:columns, column.name, "select") do |c|
+        skip!("no SQL attribute, the value comes from #{column.method ? "method :#{column.method}" : "the record"}") if column.attribute.blank?
+
+        relation = build_table.filtered_scope.select(Arel.sql(column.attribute)).limit(1)
+        c.sql = relation.to_sql
+        relation.load
+      end
+    end
+
+    def verify_column_sort(column)
+      check(:columns, column.name, "sort asc/desc") do
+        %i[asc desc].each { |direction| build_table(order: {column.name => direction}).ordered_scope.limit(1).load }
+      end
+    end
+
+    def verify_column_render(column)
+      visible = check(:columns, column.name, "visible", quiet: true) { column.visible? }
+      return if visible.nil?
+
+      formats = @table.exportable? ? %i[html csv] : %i[html]
+      formats.each do |format|
+        check(:columns, column.name, "render #{format}") do
+          skip!("not visible") unless visible
+
+          sample_rows!.each { |row| Mensa::Cell.new(row: row, column: column).render(format) }
+        end
+      end
+    end
+
+    # Filters
+
+    def verify_filters
+      @table.columns.select(&:filter?).each do |column|
+        operators = check(:filters, column.name, "operators", quiet: true) { column.filter.operators }
+        next unless operators
+
+        values = check(:filters, column.name, "collection", quiet: true) { filter_values(column) }
+        next unless values
+
+        if operators.any? { |operator, *| operator == :is_current }
+          reason = check(:filters, column.name, "is_current", quiet: true) { missing_current_reason(column) }
+          if reason
+            operators = operators.reject { |operator, *| operator == :is_current }
+            check(:filters, column.name, "is_current") { skip!(reason) }
+          end
+        end
+
+        check(:filters, column.name, filter_check_name(column, operators, values)) do |c|
+          errors = operators.filter_map { |operator, _label, with_value| filter_error(column, operator, filter_value(column, operator, with_value, values)) }
+          next if errors.empty?
+
+          c.sql = errors.first[:sql]
+          raise Failure, errors.map { |error| error[:message] }.join("\n")
+        end
+      end
+    end
+
+    def filter_check_name(column, operators, values)
+      "#{operators.map(&:first).join(", ")} (#{(column.filter.multiple? ? values : values.first).inspect})"
+    end
+
+    # Applies the filter with one operator in its own savepoint, returns
+    # {message:, sql:} when it fails
+    def filter_error(column, operator, value)
+      relation = nil
+      savepoint do
+        table = build_table(filters: {column.name => {operator: operator, value: value}.compact})
+        relation = table.filtered_scope.limit(SAMPLE_SIZE)
+        relation.load
+        # The filter pill's text
+        table.active_filters.each(&:to_s)
+      end
+      nil
+    rescue StandardError, NotImplementedError => e
+      sql = e.sql if e.respond_to?(:sql)
+      sql ||= relation.to_sql if relation
+      {message: "#{operator}#{" #{value.inspect}" if value}: #{e.class}: #{e.message}", sql: sql}
+    end
+
+    # is_current compares with Current.<column>, which needs context such as
+    # a user. Returns why it can't be checked, nil when it can.
+    def missing_current_reason(column)
+      value = begin
+        ::Current.public_send(column.name)
+      rescue NoMethodError => e
+        return "Current.#{column.name} raised #{e.message}, give the verifier a context (user:, context:)"
+      end
+      "Current.#{column.name} is nil, give the verifier a context (user:, context:)" if value.nil?
+    end
+
+    # The first values of the filter's collection, or a synthetic value
+    def filter_values(column)
+      collection = Array(column.filter.collection).filter_map { |item| item.is_a?(Array) ? item.last : item }
+      values = collection.compact_blank.first(2).map(&:to_s)
+      values.presence || [synthetic_value(column)]
+    end
+
+    def filter_value(column, operator, with_value, values)
+      return unless with_value
+      return values if column.filter.multiple? && %i[is isnt].include?(operator)
+
+      values.first
+    end
+
+    # A value as the filter popover would send it for the column's type
+    def synthetic_value(column)
+      case column.type
+      when :integer, :bigint, :decimal, :float then "1"
+      when :date then Date.current.iso8601
+      when :datetime, :timestamp, :time then Time.current.strftime("%Y-%m-%dT%H:%M")
+      when :boolean then "true"
+      when :uuid then SecureRandom.uuid
+      else "a"
+      end
+    end
+
+    # Search
+
+    # Both search modes, the app may switch between them
+    def verify_search
+      term = search_term
+
+      %i[basic fuzzy].each do |mode|
+        check(:search, nil, "#{mode} #{term.inspect}") do |c|
+          with_search_mode(mode) do
+            table = build_table(query: term)
+            skip!("needs the pg_trgm extension") if mode == :fuzzy && !table.send(:fuzzy_search?, table.scope)
+
+            relation = table.ordered_scope.limit(SAMPLE_SIZE)
+            c.sql = relation.to_sql
+            relation.load
+          end
+        end
+      end
+    end
+
+    def with_search_mode(mode)
+      previous = Mensa.config.search
+      Mensa.config.search = mode
+      yield
+    ensure
+      Mensa.config.search = previous
+    end
+
+    # A word from the first string value in the records, so it finds something
+    def search_term
+      (@rows || []).first(SAMPLE_SIZE).each do |row|
+        @table.display_columns.each do |column|
+          value = row.value(column)
+          return value.split.first.first(20) if value.is_a?(String) && value.split.first.present?
+        end
+      end
+      "a"
+    rescue
+      "a"
+    end
+
+    # Rendering, like the app's views and Mensa's controllers do
+
+    def verify_rendering
+      check(:render, nil, "table component") { view_context.table(table_name, params: params) }
+      check(:render, nil, "rows and filter pills") { render_page(build_table, view: @table.default_system_view) }
+
+      check(:render, nil, "row link") { sample_rows!.each(&:link) } if @table.link
+
+      return unless @table.actions?
+
+      @table.actions.each do |action|
+        check(:render, :actions, action.name.to_s) do
+          sample_rows!.each { |row| view_context.render(Mensa::RowAction::Component.new(table: @table, row: row, action: action)) }
+        end
+      end
+    end
+
+    # What Mensa::TablesController#show renders into the table's turbo frame
+    def render_page(table, view: nil)
+      table.table_view = view
+      view_context.render(Mensa::FilterPillList::Component.new(table: table))
+      view_context.render(Mensa::View::Component.new(table))
+    end
+
+    # Exports, generated by Mensa::ExportJob like a user's export request,
+    # for the first page of the table and of each view
+
+    def verify_exports
+      unless @table.exportable?
+        check(:exports, nil, "csv") { skip!("exportable false") }
+        return
+      end
+
+      check(:exports, nil, export_format) { verify_export({}) }
+
+      @table.system_views.each do |view|
+        # The browser sends the view's state along with the export request
+        config = (view.config || {}).deep_symbolize_keys.slice(:filters, :column_order, :hidden_columns, :group_by, :order)
+        next if config.empty?
+
+        check(:exports, view.id, export_format) { verify_export(config) }
+      end
+
+      return unless @table.supports_custom_views?
+
+      saved_views.each do |view|
+        check(:exports, "saved view #{view.id}", export_format) { verify_export({}, table_view: view) }
+      end
+    end
+
+    def export_format
+      @table.export_with_password? ? "csv (zip with password)" : "csv"
+    end
+
+    def verify_export(config, table_view: nil)
+      config = JSON.parse({params: params.presence, page: 1}.compact.merge(config).to_json)
+      export = Mensa::Export.new(
+        table_name: table_name, table_view_id: table_view&.id, format: "plain_csv", scope: "current_page",
+        config: config, created_at: Time.current
+      )
+
+      file, filename, content_type = Mensa::ExportJob.new.generate_file(export)
+      raise Failure, "the export job generated no file" unless file
+
+      data = file.read
+      file.close!
+      csv = (content_type == "application/zip") ? unzip(data, export.password) : data
+      raise Failure, "#{filename} is empty" if csv.blank?
+
+      expected = build_table((table_view&.config || {}).deep_symbolize_keys.merge(config.deep_symbolize_keys))
+      headers = expected.display_columns.map { |column| column.name.to_s }
+      lines = CSV.parse(csv.force_encoding(Encoding::UTF_8).delete_prefix("\uFEFF"))
+      raise Failure, "the export has no columns" if headers.empty?
+      raise Failure, "the export has headers #{lines.first.inspect}, expected #{headers.inspect}" unless lines.first == headers
+
+      records = expected.rows.size
+      raise Failure, "the export has #{lines.size - 1} records, expected #{records}" unless lines.size - 1 == records
+    end
+
+    def unzip(data, password)
+      require "zip"
+
+      Zip::InputStream.open(StringIO.new(data), decrypter: Zip::TraditionalDecrypter.new(password)) do |zip|
+        zip.get_next_entry
+        zip.read
+      end
+    end
+
+    # Grouping and aggregates
+
+    def verify_grouping
+      groupable = @table.columns.select(&:groupable?)
+      relation = @table.scope.is_a?(ActiveRecord::Relation)
+
+      if @table.config[:group_by].present? || @table.config[:aggregates].present?
+        check(:grouping, nil, "configured group_by/aggregates") do
+          problems = grouping_problems(@table, @table.config)
+          raise Failure, problems.join("\n") if problems.any?
+
+          render_page(build_table)
+        end
+      end
+
+      groupable.each do |column|
+        check(:grouping, column.name, "group by") do
+          skip!("the scope is not an ActiveRecord::Relation") unless relation
+
+          render_page(build_table(group_by: column.name, aggregates: {}))
+        end
+      end
+
+      @table.columns.select(&:aggregatable?).reject(&:internal?).each do |column|
+        column.aggregates.each do |function|
+          check(:grouping, column.name, function.to_s) do
+            skip!("no groupable column to group by") if groupable.empty?
+            skip!("the scope is not an ActiveRecord::Relation") unless relation
+
+            render_page(build_table(group_by: groupable.first.name, aggregates: {column.name => function}))
+          end
+        end
+      end
+    end
+
+    # Mensa ignores a group_by or aggregates it can't use, report them instead
+    def grouping_problems(table, config)
+      problems = []
+
+      group_by = config[:group_by].presence
+      if group_by && !table.column(group_by)&.groupable?
+        problems << "group_by :#{group_by} is not a groupable column (groupable true, with an SQL attribute)"
+      end
+
+      (config[:aggregates].presence || {}).to_h.each do |name, function|
+        column = table.column(name)
+        unless column&.aggregates&.map(&:to_s)&.include?(function.to_s)
+          problems << "aggregates #{name}: :#{function} is not allowed, the column allows #{column&.aggregates.presence&.inspect || "none"}"
+        end
+      end
+
+      problems
+    end
+
+    # Views
+
+    def verify_views
+      @table.system_views.each do |view|
+        check(:views, view.id, view.name.to_s) do
+          config = (view.config || {}).deep_symbolize_keys
+          problems = config_problems(config)
+          raise Failure, problems.join("\n") if problems.any?
+
+          render_page(build_table(config), view: view)
+        end
+      end
+
+      return unless @table.supports_custom_views?
+
+      saved_views.each do |view|
+        check(:views, "saved view #{view.id}", view.name.to_s) { render_page(build_table((view.config || {}).deep_symbolize_keys), view: view) }
+      end
+    end
+
+    def saved_views
+      Mensa::TableView.where(table_name: table_name, user: [nil, @table.current_user].uniq).order(:created_at).limit(25).to_a
+    end
+
+    # References to columns (in a view or the table's defaults) that Mensa
+    # would silently ignore
+    def config_problems(config)
+      names = @table.columns.map(&:name)
+      problems = []
+
+      (config[:filters] || {}).each_key { |name| problems << "filter on unknown column :#{name}" unless names.include?(name.to_sym) }
+      Array(config[:hidden_columns]).each { |name| problems << "hidden_columns has unknown column :#{name}" unless names.include?(name.to_sym) }
+      Array(config[:column_order]).each { |name| problems << "column_order has unknown column :#{name}" unless names.include?(name.to_sym) }
+      (config[:order] || {}).each do |name, direction|
+        problems << "order on unknown column :#{name}" unless names.include?(name.to_sym) || @table.model.column_names.include?(name.to_s)
+        problems << "order :#{name} has direction #{direction.inspect}, expected :asc or :desc" unless %w[asc desc].include?(direction.to_s.downcase)
+      end
+      problems + grouping_problems(@table, config)
+    end
+
+    # Transaction and context
+
+    def read_only_transaction
+      ActiveRecord::Base.while_preventing_writes do
+        ActiveRecord::Base.transaction(requires_new: true) do
+          connection = ActiveRecord::Base.connection
+          connection.execute("SET LOCAL transaction_read_only = on") if connection.adapter_name.downcase.include?("postg")
+          yield
+          raise ActiveRecord::Rollback
+        end
+      end
+    end
+
+    def with_current_attributes(&)
+      attributes = context.symbolize_keys
+      attributes[:user] = user if user
+      attributes[:account] = account if account
+      return yield if attributes.empty?
+
+      raise ArgumentError, "Mensa::Verifier: setting #{attributes.keys.join(", ")} needs a Current class" unless defined?(::Current)
+
+      unknown = attributes.keys.reject { |key| ::Current.respond_to?(:"#{key}=") }
+      raise ArgumentError, "Mensa::Verifier: Current has no attribute(s) #{unknown.join(", ")}" if unknown.any?
+
+      # The stored values, Current.set would restore what the getters return
+      stored = ::Current.attributes.symbolize_keys if ::Current.respond_to?(:attributes)
+      previous = attributes.keys.to_h { |key| [key, stored ? stored[key] : ::Current.public_send(key)] }
+      attributes.each { |key, value| ::Current.public_send(:"#{key}=", value) }
+      yield
+    ensure
+      previous&.each { |key, value| ::Current.public_send(:"#{key}=", value) }
+    end
+  end
+end

data/lib/mensa/version.rb

@@ -1,3 +1,3 @@
 module Mensa
-  VERSION = "0.6.16"
+  VERSION = "0.6.18"
 end

data/lib/mensa.rb

@@ -1,6 +1,7 @@
 require "mensa/version"
 require "mensa/engine"
 require "mensa/configuration"
+require "mensa/verifier"
 require "importmap-rails"
 
 module Mensa
@@ -13,6 +14,16 @@ module Mensa
       instance
     end
 
+    # A view context of the app's base controller, for rendering tables outside
+    # a request (exports, Mensa::Verifier), with the app's (url) helpers
+    def offline_view_context(request = nil)
+      request ||= ActionDispatch::Request.new(Rack::MockRequest.env_for("http://#{Rails.application.routes.default_url_options[:host] || "localhost"}/"))
+      controller = config.base_controller.constantize.new
+      controller.set_request!(request)
+      controller.set_response!(ActionDispatch::Response.new)
+      controller.view_context
+    end
+
     def class_for_name(name)
       class_name = "#{name}_table".camelcase
       unless class_name.safe_constantize

data/lib/tasks/mensa.rake

@@ -0,0 +1,13 @@
+namespace :mensa do
+  desc "Verify a Mensa table against the database, e.g. mensa:verify[users] (context: USER_ID=, ACCOUNT_ID=, PARAMS='{...}')"
+  task :verify, [:table] => :environment do |_task, args|
+    abort "Usage: bin/rails \"mensa:verify[table_name]\"" if args[:table].blank?
+
+    exit(1) unless Mensa::Verifier.run(args[:table])
+  end
+
+  desc "Verify all Mensa tables in app/tables against the database (context: USER_ID=, ACCOUNT_ID=, PARAMS='{...}')"
+  task verify_all: :environment do
+    exit(1) unless Mensa::Verifier.run
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mensa
 version: !ruby/object:Gem::Version
-  version: 0.6.16
+  version: 0.6.18
 platform: ruby
 authors:
 - Tom de Grunt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-13 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -323,7 +323,11 @@ files:
 - lib/mensa.rb
 - lib/mensa/configuration.rb
 - lib/mensa/engine.rb
+- lib/mensa/testing.rb
+- lib/mensa/verifier.rb
+- lib/mensa/verifier/result.rb
 - lib/mensa/version.rb
+- lib/tasks/mensa.rake
 - lib/tasks/mensa_tasks.rake
 - mensa.gemspec
 - mise.toml