minitest-meaningful 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0537b67234cc8e5b97f42ac7117068392946f88ca607b2b7ff6aa0fff95b7f1f
-  data.tar.gz: 49534eacac48a362598ca178ee5b91da40ab41da44f3ab132aecbdbfeb8d78c7
+  metadata.gz: 891d5286a476cddcc75becd847de84b03c50f372fbdc028b41370f458b370221
+  data.tar.gz: 4f3f88df084f83a9aefb3c855280c0cdd35eb026b1f9ed3fc953269c6fb248ae
 SHA512:
-  metadata.gz: 4248b5451112ca9ff2dd6e96d22404b8b0aa8b4cd23ebf11f6596e365587c1737210ec33680029c3c1b2520d87aa7002f2df71ec00c4f786ea55e0a1f143a4ba
-  data.tar.gz: b777b67082ea2a943b3c01d8fbb9b3760af8c2fdafe00cdec7ce209e0d7f8ab47e94c81c8cea663da0756b77d6f848937364ce9f7604ea63100ea70f8e8d06d8
+  metadata.gz: 5e59a86d5570dc1a7f6f2d10609ba17b698517ee6f5bda575e449c60fe0b9d8f855fadcce8ce2b02b96081f1b4572bb25cec716a988ddd842507cb1feb01c04e
+  data.tar.gz: c08ba688fe760b7f0b3f6eaad0dfa44c4dddbe4819762a4d10c6bb32364ee7110ef919d09b358615b4a216eaa0e99eff2c0ca1bce6cc9ff8d853a7cc135829d2

data/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+      - run: bundle exec rake

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,76 +1,35 @@
 # Minitest::Meaningful
 
-This is a proof-of-concept Minitest plugin to help avoid writing completely meaningless tests. A meaningless test is one that always passes because of incorrect test setup. This plugin helps ensure tests aren't meaningless, by trying to make them fail.
+TODO: Delete this and the text below, and describe your gem
 
-For example, in a Rails app we might have a test that looks like this:
-
-```rb
-test "#visible_comments excludes hidden comments" do
-  post = create(:post)
-  comment = create(:comment, status: "hidden")
-
-  refute_includes post.visible_comments, comment
-end
-```
-
-The `comment` record is completely unrelated to the `post` record. It doesn't matter what the `status` is, nor does it really matter what the `#visible_comments` implementation looks like, there's no reason this comment would ever be returned. It always passes, it's a false positive test.
-
-This plugin adds an `important!` annotation to wrap the most important test setup variable. The test runner can then run the test both with and without evaluating that block. If the test passes when that `important!` block is not evaluated, then we know it is not meaningful.
-
-```rb
-test "#visible_comments excludes hidden comments" do
-  post = create(:post)
-  comment = create(:comment)
-  important! { comment.update!(status: "hidden") }
-
-  refute_includes post.visible_comments, comment
-end
-```
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/minitest/meaningful`. To experiment with that code, run `bin/console` for an interactive prompt.
 
 ## Installation
 
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add minitest-meaningful
+```bash
+bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install minitest-meaningful
-
-## Usage
-
-Include the `Minitest::Meaningful` module in your test:
-
-```rb
-class ExampleTest > Minitest::Test
-  include Minitest::Meaningful
-end
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
 ```
 
-Annotate the most important test setup variable:
-
-```rb
-def test_visible_comments_excludes_hidden_comments
-  post = create(:post)
-  comment = create(:comment)
-  important! { comment.update!(status: "hidden") }
+## Usage
 
-  refute_includes post.visible_comments, comment
-end
-```
+TODO: Write usage instructions here
 
-Assert the test should fail:
+## Development
 
-```rb
-assert_meaningful :test_visible_comments_excludes_hidden_comments
-```
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-Run the test with the `--meaningful` flag:
-
-```sh
-$ ruby example_test.rb --meaningful
-```
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-This is definitely a hacky proof-of-concept. If you can think of a better way to integrate this into Minitest test suites, or a way to more robustly identify false-positive tests, please let me know! Also, I hate the name—please suggest something better!
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/minitest-meaningful.

data/Rakefile

@@ -1,4 +1,8 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/minitest/meaningful/version.rb

@@ -2,6 +2,6 @@
 
 module Minitest
   module Meaningful
-    VERSION = "0.3.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/minitest/meaningful.rb

@@ -1,91 +1,125 @@
 # frozen_string_literal: true
 
+require "minitest"
 require_relative "meaningful/version"
 
 module Minitest
   module Meaningful
-    class << self
-      attr_accessor :enabled
+    class VacuousAssertion < Assertion; end
+
+    def assert(test, msg = nil)
+      result = super
+      unless [true, false, nil].include?(test)
+        vacuous! "assert passes for every #{test.class}. Use #{Meaningful.alternatives(test)} instead."
+      end
+      result
     end
 
-    MultipleAnnotationsError = Class.new(StandardError)
+    def assert_output(stdout = nil, stderr = nil)
+      vacuous! "assert_output makes no assertions. Pass the expected stdout or stderr." if stdout.nil? && stderr.nil?
+      super
+    end
 
-    module ClassMethods
-      def runnable_methods
-        if Meaningful.enabled
-          meaningful_methods.keys
-        else
-          super
-        end
+    def assert_raises(*exp)
+      error = super
+      if error.is_a?(NameError) && exp.grep(Module).none? { _1 <= NameError }
+        vacuous! "assert_raises caught #{error.class}: #{error.message}. Name the expected error class."
       end
+      error
+    end
 
-      def meaningful_methods
-        @meaningful_methods ||= {}
-      end
+    def refute_equal(exp, act, msg = nil)
+      result = super
+      vacuous! "refute_equal passes for every value because the actual value is nil. Use assert_nil instead." if act.nil?
+      result
+    end
 
-      def assert_meaningful(*names)
-        names.each do |name|
-          meaningful_methods[name.to_s] = caller
-        end
+    def refute_includes(collection, obj, msg = nil)
+      result = super
+      if Meaningful.empty?(collection)
+        vacuous! "refute_includes passes for every object because the collection is empty. Use assert_empty instead."
       end
+      result
     end
 
-    def self.included(base)
-      base.extend(ClassMethods)
+    def refute_instance_of(cls, obj, msg = nil)
+      result = super
+      vacuous! "refute_instance_of passes for every class because the object is nil. Use assert_nil instead." if obj.nil?
+      result
     end
 
+    def refute_kind_of(cls, obj, msg = nil)
+      result = super
+      vacuous! "refute_kind_of passes for every class because the object is nil. Use assert_nil instead." if obj.nil?
+      result
+    end
 
-    def run
-      @should_fail = Meaningful.enabled
+    def refute_match(matcher, obj, msg = nil)
+      result = super
+      vacuous! "refute_match passes for every pattern because the subject is nil. Use assert_nil instead." if obj.nil?
+      vacuous! "refute_match passes because the subject is empty. Use assert_empty instead." if obj == ""
+      result
+    end
 
+    def refute_operator(o1, op, *)
+      result = super
+      if %i[include? member? key? has_key?].include?(op.to_sym) && Meaningful.empty?(o1)
+        vacuous! "refute_operator passes for every object because the receiver is empty. Use assert_empty instead."
+      end
+      result
+    end
+
+    def refute_respond_to(obj, *, **)
+      result = super
+      vacuous! "refute_respond_to passes for every method because the object is nil. Use assert_nil instead." if obj.nil?
+      result
+    end
+
+    def refute_same(exp, act, msg = nil)
+      result = super
+      vacuous! "refute_same passes because the objects are not equal. Use refute_equal instead." if exp != act
+      result
+    end
+
+    def after_teardown
       super
+      return unless assertions.zero? && failures.empty?
 
-      if @should_fail
-        if !@important_backtrace
-          exception = Minitest::Assertion.new("Expected test to have `important!` setup.")
-          exception.set_backtrace(self.class.meaningful_methods[name.to_s])
-          self.failures << exception
-        elsif !@did_fail
-          exception = Minitest::Assertion.new("Expected test to fail without `important!` setup.")
-          exception.set_backtrace(@important_backtrace)
-          self.failures << exception
-        end
-      end
+      error = VacuousAssertion.new("Vacuous test: it makes no assertions.")
+      error.set_backtrace(method(name).source_location.join(":"))
+      raise error
+    end
 
-      Result.from(self)
-    rescue MultipleAnnotationsError
-      exception = Minitest::Assertion.new("Test uses `important!` more than once.")
-      exception.set_backtrace(@important_backtrace)
-      self.failures << exception
+    def self.alternatives(value)
+      case value
+      when Integer then "refute_nil, assert_operator or assert_match"
+      when String then "refute_nil, refute_empty or assert_match"
+      when Array, Hash then "refute_nil or refute_empty"
+      else "refute_nil"
+      end
+    end
 
-      Result.from(self)
+    def self.empty?(collection)
+      collection.respond_to?(:empty?) && collection.empty?
     end
 
-    def capture_exceptions
-      return super unless @should_fail
+    private
 
-      yield
-    rescue *Minitest::Test::PASSTHROUGH_EXCEPTIONS
-      raise
-    rescue Assertion => e
-      @did_fail = true
+    def vacuous!(message)
+      raise VacuousAssertion, "Vacuous assertion: #{message}" if called_by_test?
     end
 
-    def important!
-      if @should_fail
-        if @important_backtrace
-          raise MultipleAnnotationsError
-        else
-          @important_backtrace = caller
-        end
-      else
-        unless self.class.meaningful_methods.keys.include?(name.to_s)
-          exception = Minitest::Assertion.new("Test uses `important!` without `assert_meaningful`.")
-          raise exception
-        end
+    # Minitest assertions call each other, and other gems call assertions
+    # from their own helpers. Only calls written in the test code are checked.
+    def called_by_test?
+      Thread.each_caller_location do |location|
+        path = location.path
+        next if path == __FILE__ || path.end_with?("minitest/spec.rb")
 
-        yield
+        return Gem.path.none? { path.start_with?(_1) }
       end
     end
   end
+
+  Test.include Meaningful
 end

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: minitest-meaningful
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Thomas Marshall
 autorequire:
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2024-04-01 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '7'
 description:
 email:
 - thomas@thomasmarshall.com
@@ -31,11 +37,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
+- LICENSE
 - README.md
 - Rakefile
 - lib/minitest/meaningful.rb
 - lib/minitest/meaningful/version.rb
-- lib/minitest/meaningful_plugin.rb
 homepage: https://github.com/thomasmarshall/minitest-meaningful
 licenses: []
 metadata:
@@ -49,15 +56,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: A minitest plugin to prevent false positive tests.
+summary: A minitest plugin to fail vacuous assertions.
 test_files: []

data/lib/minitest/meaningful_plugin.rb

@@ -1,13 +0,0 @@
-require "minitest/meaningful"
-
-module Minitest
-  def self.plugin_meaningful_options(opts, options)
-    opts.on "--meaningful", "Expect tests not to pass with important test setup removed." do
-      options[:meaningful] = true
-    end
-  end
-
-  def self.plugin_meaningful_init(options)
-    Meaningful.enabled = options.fetch(:meaningful, false)
-  end
-end