mutation_tester 1.2.0

data/examples/calculator_spec.rb

@@ -0,0 +1,105 @@
+require_relative 'calculator'
+
+RSpec.describe Calculator do
+  subject(:calculator) { described_class.new }
+
+  describe '#add' do
+    it 'adds two numbers' do
+      expect(calculator.add(2, 3)).to eq(5)
+    end
+
+    it 'adds negative numbers' do
+      expect(calculator.add(-2, -3)).to eq(-5)
+    end
+  end
+
+  describe '#subtract' do
+    it 'subtracts two numbers' do
+      expect(calculator.subtract(5, 3)).to eq(2)
+    end
+
+    it 'handles negative results' do
+      expect(calculator.subtract(3, 5)).to eq(-2)
+    end
+  end
+
+  describe '#multiply' do
+    it 'multiplies two numbers' do
+      expect(calculator.multiply(3, 4)).to eq(12)
+    end
+
+    it 'multiplies by zero' do
+      expect(calculator.multiply(5, 0)).to eq(0)
+    end
+  end
+
+  describe '#divide' do
+    it 'divides two numbers' do
+      expect(calculator.divide(10, 2)).to eq(5)
+    end
+
+    it 'returns 0 when dividing by zero' do
+      expect(calculator.divide(10, 0)).to eq(0)
+    end
+
+    it 'handles integer division' do
+      expect(calculator.divide(7, 2)).to eq(3)
+    end
+  end
+
+  describe '#is_positive?' do
+    it 'returns true for positive numbers' do
+      expect(calculator.is_positive?(5)).to be true
+    end
+
+    it 'returns false for negative numbers' do
+      expect(calculator.is_positive?(-5)).to be false
+    end
+
+    it 'returns false for zero' do
+      expect(calculator.is_positive?(0)).to be false
+    end
+  end
+
+  describe '#is_even?' do
+    it 'returns true for even numbers' do
+      expect(calculator.is_even?(4)).to be true
+    end
+
+    it 'returns false for odd numbers' do
+      expect(calculator.is_even?(3)).to be false
+    end
+
+    it 'returns true for zero' do
+      expect(calculator.is_even?(0)).to be true
+    end
+  end
+
+  describe '#max' do
+    it 'returns the larger number when first is larger' do
+      expect(calculator.max(5, 3)).to eq(5)
+    end
+
+    it 'returns the larger number when second is larger' do
+      expect(calculator.max(3, 5)).to eq(5)
+    end
+
+    it 'returns the number when both are equal' do
+      expect(calculator.max(5, 5)).to eq(5)
+    end
+  end
+
+  describe '#absolute' do
+    it 'returns positive number unchanged' do
+      expect(calculator.absolute(5)).to eq(5)
+    end
+
+    it 'returns absolute value of negative number' do
+      expect(calculator.absolute(-5)).to eq(5)
+    end
+
+    it 'returns zero for zero' do
+      expect(calculator.absolute(0)).to eq(0)
+    end
+  end
+end

data/examples/github_actions/ai_mutation_gate.yml

@@ -0,0 +1,75 @@
+# AI mutation gate for GitHub Actions (mutation_tester gem). Runs mutation_test
+# --json, publishes the SURVIVING mutants (file/line/original/mutated = test
+# gaps) to the job summary and a survivors.json artifact for an AI agent, then
+# re-fails on a low score. Copy to .github/workflows/, edit "EDIT:" lines. Needs
+# jq (preinstalled on ubuntu runners); see mutation_test.yml for the plain gate.
+
+name: AI Mutation Gate
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  mutation_gate:
+    name: AI mutation gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'   # EDIT: match your project's Ruby (floor is 3.0)
+          bundler-cache: true
+
+      - name: Run mutation tests (JSON report on stdout)
+        id: mutation
+        continue-on-error: true   # keep going so the worklist/artifact below still run
+        run: |
+          # EDIT: replace with YOUR source file and its test file.
+          bundle exec mutation_test --json \
+            app/models/user.rb spec/models/user_spec.rb > mutation_report.json
+
+      - name: Summarize surviving mutants (test gaps) in the job summary
+        if: always()
+        run: |
+          score=$(jq -r '.summary.mutation_score // "n/a"' mutation_report.json)
+          survivors=$(jq '[.mutations[] | select(.status == "survived")] | length' mutation_report.json)
+          {
+            echo "## Mutation gate"
+            echo "Score: **${score}%** - surviving mutants: **${survivors}**"
+            if [ "$survivors" -eq 0 ]; then
+              echo "No surviving mutants. No test gaps to close."
+            else
+              echo "| file | line | from | to |"
+              echo "|---|---|---|---|"
+              jq -r '.mutations[] | select(.status == "survived")
+                     | "| \(.file_path) | \(.line) | `\(.original)` | `\(.mutated)` |"' \
+                     mutation_report.json
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Extract survivors as a machine-readable worklist for an AI agent
+        if: always()
+        run: |
+          jq '[.mutations[] | select(.status == "survived")
+               | {file: .file_path, line: .line, from: .original, to: .mutated,
+                  source_line: .source_line, mutated_line: .mutated_line}]' \
+             mutation_report.json > survivors.json
+          cat survivors.json  # feed this worklist to your agent CLI
+
+      - name: Upload mutation report and survivor worklist
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: |
+            mutation_report.json
+            survivors.json
+
+      - name: Enforce the gate
+        if: steps.mutation.outcome == 'failure'   # non-zero run = score below threshold
+        run: exit 1

data/examples/github_actions/mutation_test.yml

@@ -0,0 +1,87 @@
+# Mutation testing in CI with GitHub Actions (mutation_tester gem).
+#
+# Copy this file to .github/workflows/mutation_test.yml in your project and you
+# have mutation testing running in CI in about five minutes. The workflow:
+#   1. checks out your code,
+#   2. installs Ruby and your bundle (with mutation_tester in it),
+#   3. runs mutation_test on your source file and its test file,
+#   4. uploads the HTML/JSON reports as a build artifact (even on failure),
+#   5. fails the job when the mutation score is below your threshold.
+#
+# Prerequisite: add the gem to your project's Gemfile so `bundle exec` finds it:
+#   bundle add mutation_tester --group development,test
+# (or add `gem "mutation_tester"` to your development/test group, then bundle install).
+#
+# Then look for the lines marked "EDIT:" and point them at your own files.
+
+name: Mutation Testing
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  mutation_test:
+    name: Mutation testing
+    runs-on: ubuntu-latest
+    # Mutation testing re-runs your suite once per mutant, so give the job more
+    # head-room than a normal test run. Tune this to your project's size.
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          # EDIT: match the Ruby version your project uses.
+          ruby-version: '3.3'
+          # Runs `bundle install` and caches the resolved gems between runs.
+          bundler-cache: true
+
+      - name: Run mutation tests
+        # EDIT: replace with YOUR source file and its test file.
+        # The CLI exits non-zero when the score is below the threshold, which
+        # fails this step (and the job). That is your quality gate: no extra
+        # configuration needed.
+        run: bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb
+        # OPTIONAL - run mutants in parallel to finish faster. This works out of
+        # the box (see MUTATION_TESTER_PARALLEL_PROCESSES). Enable it only if
+        # your tests do not share database state. Uncomment the two lines below:
+        # env:
+        #   MUTATION_TESTER_PARALLEL_PROCESSES: 4
+
+      # OPTIONAL - test several source/test pairs in one job. Uncomment and give
+      # each pair its own --output-dir so their reports do not overwrite each
+      # other. The job stops at the first pair that is below its threshold.
+      # - name: Run mutation tests (multiple files)
+      #   run: |
+      #     bundle exec mutation_test app/models/user.rb spec/models/user_spec.rb \
+      #       --output-dir tmp/mutation_reports/user
+      #     bundle exec mutation_test app/models/order.rb spec/models/order_spec.rb \
+      #       --output-dir tmp/mutation_reports/order
+
+      # OPTIONAL - incremental gate for pull requests: mutate only the files
+      # changed since the PR base branch and stop at the first surviving mutant.
+      # This keeps the job fast on large repos. Two edits are needed:
+      #   1. give the Checkout step the full history so git can diff against the
+      #      base branch:
+      #        with:
+      #          fetch-depth: 0
+      #   2. replace the "Run mutation tests" step with the incremental run:
+      # - name: Run mutation tests (changed files only)
+      #   if: github.event_name == 'pull_request'
+      #   run: |
+      #     bundle exec mutation_test --glob 'lib/**/*.rb' \
+      #       --since "origin/${{ github.base_ref }}" --fail-fast
+
+      - name: Upload mutation reports
+        # always() uploads the reports even when the gate failed the job, which
+        # is exactly when you want to inspect the surviving mutants.
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-reports
+          # Default output_dir; change it if you pass a custom --output-dir above.
+          path: tmp/mutation_reports/

data/examples/hooks/pre-push

@@ -0,0 +1,41 @@
+#!/bin/sh
+#
+# mutation_tester pre-push hook - block a push when the mutation score of your
+# target file(s) drops below THRESHOLD, so weak tests never reach the remote.
+#
+# Install:  cp examples/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+#           (lefthook/overcommit users: call this script from your pre-push step)
+# Requires: jq (https://jqlang.github.io/jq/)
+# On a block it prints the surviving mutants (file:line, what changed) = the gaps.
+
+set -eu
+
+THRESHOLD=90   # EDIT: minimum mutation score (percent) required to allow the push
+report=$(mktemp)
+status=0
+
+# EDIT: the "SOURCE TEST" pairs to gate on, one per line. The loop reads this
+# heredoc (not a pipe), so it runs in the current shell and $status survives it.
+while read -r source test; do
+  [ -z "$source" ] && continue
+
+  # --json prints ONLY the JSON to stdout; we do our own jq threshold check, so
+  # ignore the CLI's own pass/fail exit here.
+  bundle exec mutation_test --json "$source" "$test" >"$report" || true
+
+  score=$(jq -r '.summary.mutation_score // empty' "$report")
+  if [ -z "$score" ] || jq -e --argjson t "$THRESHOLD" '.summary.mutation_score < $t' "$report" >/dev/null; then
+    echo "BLOCK: $source scored ${score:-no}% (< ${THRESHOLD}%). Surviving mutants (test gaps):" >&2
+    jq -r '.mutations[] | select(.status == "survived")
+           | "  \(.file_path):\(.line)  \(.original) -> \(.mutated)"' "$report" >&2
+    status=1
+  else
+    echo "OK: $source scored ${score}% (>= ${THRESHOLD}%)" >&2
+  fi
+done <<'PAIRS'
+app/models/user.rb spec/models/user_spec.rb
+PAIRS
+
+rm -f "$report"
+[ "$status" -eq 0 ] || echo "Push blocked by mutation gate. Close the gaps above or lower THRESHOLD." >&2
+exit "$status"

data/examples/run_example.rb

@@ -0,0 +1,31 @@
+require_relative '../lib/mutation_tester'
+
+MutationTester.configure do |config|
+  config.reporters = %i[console html json]
+  config.minimum_score = 90
+  config.verbose = true
+  config.fail_on_threshold = true
+end
+
+source_file = File.expand_path('calculator.rb', __dir__)
+spec_file = File.expand_path('calculator_spec.rb', __dir__)
+
+unless File.exist?(source_file)
+  puts Rainbow("❌ Source file not found: #{source_file}").red
+  exit 1
+end
+
+unless File.exist?(spec_file)
+  puts Rainbow("❌ Spec file not found: #{spec_file}").red
+  exit 1
+end
+
+success = MutationTester.run(source_file, spec_file)
+
+if success
+  puts "\n" + Rainbow('✅ Example completed!').green
+  puts Rainbow('Check mutation_reports/mutation_report.html for detailed results').cyan
+else
+  puts "\n" + Rainbow('❌ Example failed!').red
+  exit 1
+end

data/examples/run_example_minitest.rb

@@ -0,0 +1,38 @@
+require_relative '../lib/mutation_tester'
+
+puts Rainbow('=' * 80).bright
+puts Rainbow('🧬 Minitest Example (Serial Execution)').cyan.bold
+puts Rainbow('=' * 80).bright
+puts ''
+
+MutationTester.configure do |config|
+  config.parallel_processes = 1
+  config.reporters = %i[console html json]
+  config.minimum_score = 90
+  config.verbose = true
+  config.fail_on_threshold = false
+  config.output_dir = 'mutation_reports'
+end
+
+source_file = File.expand_path('calculator.rb', __dir__)
+spec_file = File.expand_path('calculator_minitest.rb', __dir__)
+
+unless File.exist?(source_file)
+  puts Rainbow("❌ Source file not found: #{source_file}").red
+  exit 1
+end
+
+unless File.exist?(spec_file)
+  puts Rainbow("❌ Test file not found: #{spec_file}").red
+  exit 1
+end
+
+success = MutationTester.run(source_file, spec_file)
+
+puts ''
+if success
+  puts Rainbow('✅ Minitest example completed successfully!').green.bold
+else
+  puts Rainbow('⚠️  Minitest example completed with issues').yellow.bold
+end
+puts Rainbow('📊 Check mutation_reports/mutation_report.html for detailed results').cyan

data/examples/run_example_parallel_minitest.rb

@@ -0,0 +1,48 @@
+require_relative '../lib/mutation_tester'
+require 'parallel'
+
+puts Rainbow('=' * 80).bright
+puts Rainbow('🧬 Minitest Example (Parallel Execution)').cyan.bold
+puts Rainbow('=' * 80).bright
+puts ''
+
+num_processors = Parallel.processor_count
+puts Rainbow("💻 Detected #{num_processors} processor(s), using parallel execution").cyan
+puts ''
+
+MutationTester.configure do |config|
+  config.parallel_processes = [num_processors, 2].max
+  config.reporters = %i[console html json]
+  config.minimum_score = 90
+  config.verbose = true
+  config.fail_on_threshold = false
+  config.output_dir = 'mutation_reports'
+end
+
+source_file = File.expand_path('calculator.rb', __dir__)
+spec_file = File.expand_path('calculator_minitest.rb', __dir__)
+
+unless File.exist?(source_file)
+  puts Rainbow("❌ Source file not found: #{source_file}").red
+  exit 1
+end
+
+unless File.exist?(spec_file)
+  puts Rainbow("❌ Test file not found: #{spec_file}").red
+  exit 1
+end
+
+start_time = Time.now
+success = MutationTester.run(source_file, spec_file)
+elapsed_time = Time.now - start_time
+
+puts ''
+puts Rainbow("⏱️  Completed in #{elapsed_time.round(2)} seconds").cyan
+puts ''
+
+if success
+  puts Rainbow('✅ Parallel Minitest example completed successfully!').green.bold
+else
+  puts Rainbow('⚠️  Parallel Minitest example completed with issues').yellow.bold
+end
+puts Rainbow('📊 Check mutation_reports/mutation_report.html for detailed results').cyan

data/examples/run_example_parallel_rspec.rb

@@ -0,0 +1,48 @@
+require_relative '../lib/mutation_tester'
+require 'parallel'
+
+puts Rainbow('=' * 80).bright
+puts Rainbow('🧬 RSpec Example (Parallel Execution)').cyan.bold
+puts Rainbow('=' * 80).bright
+puts ''
+
+num_processors = Parallel.processor_count
+puts Rainbow("💻 Detected #{num_processors} processor(s), using parallel execution").cyan
+puts ''
+
+MutationTester.configure do |config|
+  config.parallel_processes = [num_processors, 2].max
+  config.reporters = %i[console html json]
+  config.minimum_score = 90
+  config.verbose = true
+  config.fail_on_threshold = false
+  config.output_dir = 'mutation_reports'
+end
+
+source_file = File.expand_path('calculator.rb', __dir__)
+spec_file = File.expand_path('calculator_spec.rb', __dir__)
+
+unless File.exist?(source_file)
+  puts Rainbow("❌ Source file not found: #{source_file}").red
+  exit 1
+end
+
+unless File.exist?(spec_file)
+  puts Rainbow("❌ Spec file not found: #{spec_file}").red
+  exit 1
+end
+
+start_time = Time.now
+success = MutationTester.run(source_file, spec_file)
+elapsed_time = Time.now - start_time
+
+puts ''
+puts Rainbow("⏱️  Completed in #{elapsed_time.round(2)} seconds").cyan
+puts ''
+
+if success
+  puts Rainbow('✅ Parallel RSpec example completed successfully!').green.bold
+else
+  puts Rainbow('⚠️  Parallel RSpec example completed with issues').yellow.bold
+end
+puts Rainbow('📊 Check mutation_reports/mutation_report.html for detailed results').cyan

data/examples/run_example_rspec.rb

@@ -0,0 +1,38 @@
+require_relative '../lib/mutation_tester'
+
+puts Rainbow('=' * 80).bright
+puts Rainbow('🧬 RSpec Example (Serial Execution)').cyan.bold
+puts Rainbow('=' * 80).bright
+puts ''
+
+MutationTester.configure do |config|
+  config.parallel_processes = 1
+  config.reporters = %i[console html json]
+  config.minimum_score = 90
+  config.verbose = true
+  config.fail_on_threshold = false
+  config.output_dir = 'mutation_reports'
+end
+
+source_file = File.expand_path('calculator.rb', __dir__)
+spec_file = File.expand_path('calculator_spec.rb', __dir__)
+
+unless File.exist?(source_file)
+  puts Rainbow("❌ Source file not found: #{source_file}").red
+  exit 1
+end
+
+unless File.exist?(spec_file)
+  puts Rainbow("❌ Spec file not found: #{spec_file}").red
+  exit 1
+end
+
+success = MutationTester.run(source_file, spec_file)
+
+puts ''
+if success
+  puts Rainbow('✅ RSpec example completed successfully!').green.bold
+else
+  puts Rainbow('⚠️  RSpec example completed with issues').yellow.bold
+end
+puts Rainbow('📊 Check mutation_reports/mutation_report.html for detailed results').cyan

data/examples/spec_helper.rb

@@ -0,0 +1,21 @@
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with(:rspec) do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching(:focus)
+  config.example_status_persistence_file_path = 'spec/examples.txt'
+  config.disable_monkey_patching!
+  config.warnings = false
+
+  config.default_formatter = 'doc' if config.files_to_run.one?
+
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
+end