rubocop-dev_doc 0.2.0 → 0.3.1

data/lib/rubocop/cop/dev_doc/test/response_assert_equal.rb

@@ -0,0 +1,179 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Controller tests that assert on the rendered `response.body` should
+        # also snapshot the full response with `response_assert_equal`.
+        #
+        # ## Rationale
+        # `response_assert_equal` (glib-web's `Glib::TestHelpers`) is the most
+        # blackbox assertion available — it snapshots the entire rendered
+        # response, so it catches regressions anywhere in the output, not just
+        # the one substring a targeted assertion happens to check. Per the
+        # testing best practice, happy- and unhappy-path controller tests
+        # should always use it.
+        #
+        # The common slip this cop guards against: a test inspects the rendered
+        # body with `assert_match` / `assert_no_match` / `assert_includes` /
+        # `response.body.scan(...)` but forgets the snapshot. The targeted
+        # assertion documents intent, but on its own it only proves the one
+        # line — collateral changes elsewhere in the response slip through.
+        #
+        #   ❌ Inspects the body, but no snapshot
+        #   test 'index lists the item' do
+        #     get items_url(format: :json)
+        #     assert_response :success
+        #     assert_match 'Widget', response.body
+        #   end
+        #
+        #   ✔️ Keep the focused assertion AND snapshot the whole response
+        #   test 'index lists the item' do
+        #     get items_url(format: :json)
+        #     assert_response :success
+        #     assert_match 'Widget', response.body
+        #     response_assert_equal
+        #   end
+        #
+        # ## What is NOT flagged
+        # - Tests that already call `response_assert_equal`.
+        # - Exception/redirect paths — a test asserting a non-success status
+        #   (`assert_response :not_found`, `:forbidden`, `:redirect`, etc.)
+        #   often has no stable rendered body to snapshot.
+        # - State-change tests that never read `response.body` (e.g.
+        #   `assert_difference 'Model.count'`, mailer assertions). Passing
+        #   `response.body` to a helper like `submit_form(response.body, ...)`
+        #   is not a body assertion and is not flagged.
+        #
+        # ## Inline disable
+        # For the rare happy-path test whose response is genuinely
+        # non-deterministic and cannot be made stable, add a
+        # `rubocop:disable DevDoc/Test/ResponseAssertEqual` comment to the
+        # `test '...' do` line, with a written reason on the next line
+        # (e.g. "chunked response includes a per-run boundary token").
+        #
+        # @example
+        #   # bad
+        #   test 'shows the row' do
+        #     get foo_url(format: :json)
+        #     assert_match 'bar', response.body
+        #   end
+        #
+        #   # good
+        #   test 'shows the row' do
+        #     get foo_url(format: :json)
+        #     assert_match 'bar', response.body
+        #     response_assert_equal
+        #   end
+        class ResponseAssertEqual < Base
+          MSG = 'Asserts on `response.body` but never calls `response_assert_equal`. ' \
+                'Add the snapshot assertion (usually last) — it captures the whole rendered ' \
+                'response, a stronger guard than a targeted body assertion. Exception-path ' \
+                'tests that cannot snapshot may disable this cop with a reason.'.freeze
+
+          # @!method test_block?(node)
+          def_node_matcher :test_block?, <<~PATTERN
+            (block (send nil? :test ...) _args _body)
+          PATTERN
+
+          # @!method response_body_read?(node)
+          def_node_matcher :response_body_read?, <<~PATTERN
+            (send (send nil? :response) {:body :parsed_body})
+          PATTERN
+
+          # @!method calls_snapshot?(node)
+          def_node_search :calls_snapshot?, <<~PATTERN
+            (send nil? :response_assert_equal)
+          PATTERN
+
+          # @!method response_status?(node)
+          def_node_matcher :response_status?, '(send (send nil? :response) :status)'
+
+          # Non-success HTTP statuses (symbol form). A test asserting any of
+          # these is an exception / redirect / empty-body path — no JSON body
+          # to snapshot.
+          NON_SUCCESS_STATUS_SYMBOLS = %i[
+            not_found forbidden unauthorized unprocessable_entity unprocessable_content
+            bad_request conflict gone no_content not_modified redirect moved_permanently
+            found see_other payment_required too_many_requests precondition_failed
+          ].freeze
+
+          def on_block(node)
+            return unless test_block?(node)
+            return unless node.body
+            return if calls_snapshot?(node)
+            return if exempt_from_snapshot?(node)
+            return unless inspects_response_body?(node)
+
+            add_offense(node.send_node.loc.selector)
+          end
+
+          private
+
+          # Exception / redirect / empty-body responses can't (and shouldn't) be
+          # snapshotted. Handles both the `assert_response :symbol` convention
+          # and the numeric `assert_response 404` / `assert_equal 404,
+          # response.status` convention, plus `assert_empty response.body`.
+          def exempt_from_snapshot?(test_node)
+            test_node.each_descendant(:send).any? { |s| non_snapshotable_assertion?(s) }
+          end
+
+          def non_snapshotable_assertion?(send_node)
+            case send_node.method_name
+            when :assert_response then non_success_status?(send_node.first_argument)
+            when :assert_equal then non_success_status_equal?(send_node)
+            when :assert_empty then response_body_read?(send_node.first_argument)
+            else false
+            end
+          end
+
+          # `assert_equal <non-2xx code>, response.status`
+          def non_success_status_equal?(send_node)
+            args = send_node.arguments
+            args.size >= 2 && non_success_status?(args[0]) && response_status?(args[1])
+          end
+
+          # A non-success status: a symbol (`:not_found`) or a numeric code
+          # >= 300 (`404`). 2xx codes are NOT exempt — they should snapshot.
+          def non_success_status?(node)
+            return false unless node
+
+            (node.sym_type? && NON_SUCCESS_STATUS_SYMBOLS.include?(node.value)) ||
+              (node.int_type? && node.value >= 300)
+          end
+
+          # True when the test inspects the response *as JSON*. Three forms count:
+          #   - `response.parsed_body` (any use — it's the JSON-parsed body)
+          #   - `JSON.parse(response.body)` (explicit JSON parse, even if the
+          #     result is stored in a local first)
+          #   - `response.body` directly inside an assertion
+          #     (`assert_match 'x', response.body`)
+          #
+          # Deliberately NOT counted: `response.body` fed to a format-specific
+          # parser (`parse_xlsx`, `CSV.parse`, `Nokogiri…parse`) or a render/submit
+          # helper (`submit_form`) — those are non-JSON or pass-through, and
+          # `response_assert_equal` (JSON-only) can't snapshot them.
+          def inspects_response_body?(test_node)
+            test_node.each_descendant(:send).any? do |read|
+              next false unless response_body_read?(read)
+
+              read.method_name == :parsed_body || asserted?(read) || json_parsed?(read)
+            end
+          end
+
+          # `response.body` / `response.parsed_body` read within an assertion.
+          def asserted?(read)
+            read.each_ancestor(:send).any? { |a| a.method_name.to_s.start_with?('assert') }
+          end
+
+          # `JSON.parse(response.body)` — the JSON constant specifically, so
+          # format-specific parsers (`parse_xlsx`, `CSV.parse`) don't match.
+          def json_parsed?(read)
+            parent = read.parent
+            parent&.send_type? && parent.method_name == :parse &&
+              parent.receiver&.const_type? && parent.receiver.const_name == 'JSON'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.1.0".freeze
+    VERSION = "0.3.1".freeze
   end
 end

metadata

@@ -1,14 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - dev-doc contributors
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: lint_roller
   requirement: !ruby/object:Gem::Requirement
@@ -51,16 +80,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+description:
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - config/default.yml
+- lib/dev_doc/test/best_practice_lints.rb
+- lib/dev_doc/test/lints/cron_schedule.rb
+- lib/dev_doc/test/lints/duplicate_snapshot.rb
+- lib/dev_doc/test/lints/no_file_excludes.rb
 - lib/rubocop-dev_doc.rb
+- lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
+- lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
 - lib/rubocop/cop/dev_doc/migration/amount_column_in_cents.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_conditional_schema_changes.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_json_column.rb
+- lib/rubocop/cop/dev_doc/migration/avoid_non_null.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_vague_column_names.rb
 - lib/rubocop/cop/dev_doc/migration/date_column_naming.rb
 - lib/rubocop/cop/dev_doc/migration/no_create_join_table.rb
@@ -69,21 +108,36 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb
+- lib/rubocop/cop/dev_doc/rails/bang_save_in_transaction.rb
+- lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb
 - lib/rubocop/cop/dev_doc/rails/enum_must_be_symbolized.rb
+- lib/rubocop/cop/dev_doc/rails/no_block_predicate_on_relation.rb
 - lib/rubocop/cop/dev_doc/rails/no_deliver_later_in_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/no_perform_later_in_model.rb
+- lib/rubocop/cop/dev_doc/rails/strong_parameters_expect.rb
+- lib/rubocop/cop/dev_doc/route/no_custom_actions.rb
+- lib/rubocop/cop/dev_doc/route/resource_name_number.rb
 - lib/rubocop/cop/dev_doc/route/resources_require_only.rb
 - lib/rubocop/cop/dev_doc/style/avoid_head_response.rb
 - lib/rubocop/cop/dev_doc/style/avoid_options_hash.rb
 - lib/rubocop/cop/dev_doc/style/avoid_send.rb
+- lib/rubocop/cop/dev_doc/style/minimize_variable_scope.rb
+- lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb
+- lib/rubocop/cop/dev_doc/style/repeated_bracket_read.rb
+- lib/rubocop/cop/dev_doc/style/repeated_safe_navigation_receiver.rb
 - lib/rubocop/cop/dev_doc/style/string_symbol_comparison.rb
+- lib/rubocop/cop/dev_doc/test/avoid_glib_travel_freeze.rb
+- lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb
+- lib/rubocop/cop/dev_doc/test/response_assert_equal.rb
 - lib/rubocop/dev_doc.rb
 - lib/rubocop/dev_doc/plugin.rb
 - lib/rubocop/dev_doc/version.rb
+homepage:
 licenses: []
 metadata:
   default_lint_roller_plugin: RuboCop::DevDoc::Plugin
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -98,7 +152,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.4.6
+signing_key:
 specification_version: 4
 summary: RuboCop cops enforcing dev-doc best practices
 test_files: []