rspec-atoms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fa40b012635a3c9f62c31c5977cbd9b17b4e51ac7739c19106597c9f85b06fea
+  data.tar.gz: d2a3f0fbd30b9f279c5321dd86e43bacf0884efa418fd7597cea866c5e360359
+SHA512:
+  metadata.gz: b81face24d35cb9a72209b013965279e65d6fe94d636fb2f07736e41b063375c35041eb17e33ddf6340518b87f8c81eca331ad4602dfb8b471de7523026b94bb
+  data.tar.gz: d2efc74f299d142585393684efc4d7bb35cab4ee7a6c36c4d5bd54d0bd72d48f17906a6a559c3f3f8352cba613cfc686122e7ec88c24bb6abd9c5af191141fbb

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Carbone
+
+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

@@ -0,0 +1,86 @@
+# RSpec Atoms
+
+CircleCI usually splits RSpec by file. When tests run across parallel instances, a
+slower feature spec can keep one worker busy while the others sit idle, even when
+its individual examples are small.
+
+Splitting a cohesive spec into several files only to satisfy the CI scheduler is
+unnecessary. `rspec-atoms` exposes each runnable RSpec example as a schedulable
+atom while preserving shared setup, contexts, and readable JUnit names.
+
+The gem was designed for CircleCI's dynamic test splitting, but it works in any
+environment that needs to run RSpec examples in parallel.
+
+CircleCI Smarter Testing is currently in beta. Local validation requires the
+CircleCI `testsuite` plugin; CircleCI's CI containers already include it.
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+group :test do
+  gem "rspec-atoms"
+end
+```
+
+Then run `bundle install`.
+
+## CircleCI configuration
+
+Create `.circleci/test-suites.yml`:
+
+```yaml
+---
+name: backend tests
+
+discover: >-
+  RAILS_ENV=test bundle exec rspec-atoms discover spec
+
+run: >-
+  RAILS_ENV=test bundle exec rspec-atoms run
+  --junit "<< outputs.junit >>"
+  --
+  << test.atoms >>
+
+outputs:
+  junit: /tmp/rspec/rspec.xml
+
+options:
+  dynamic-test-splitting: true
+```
+
+`<< test.atoms >>` is replaced by CircleCI with the RSpec example IDs assigned to
+the current batch. `<< outputs.junit >>` resolves to the configured JUnit path so
+CircleCI can locate the report. The gem enables its JUnit formatter automatically;
+the `--junit` option only overrides where the report is written.
+
+Invoke the test suite from the CircleCI job:
+
+```yaml
+- run:
+    name: Run RSpec with dynamic test splitting
+    command: |
+      mkdir -p /tmp/rspec
+      circleci run testsuite "backend tests"
+    when: always
+
+- store_test_results:
+    path: /tmp/rspec
+```
+
+## Local usage
+
+```bash
+bundle exec rspec-atoms discover spec
+bundle exec rspec-atoms run -- "spec/models/user_spec.rb[1:2]"
+```
+
+Local runs write JUnit XML to `tmp/rspec.xml`. Pass `--junit PATH` before `--` to
+use a different path.
+
+Validate the CircleCI configuration locally with:
+
+```bash
+circleci run testsuite "backend tests" --doctor
+```

data/exe/rspec-atoms

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rspec_atoms/cli"
+
+exit RSpecAtoms::CLI.start(ARGV)

data/lib/rspec_atoms/cli.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "discover"
+require_relative "run"
+require_relative "version"
+
+module RSpecAtoms
+  class CLI
+    EXIT_USAGE = 64
+
+    def self.start(arguments, output: $stdout, error: $stderr)
+      arguments = arguments.dup
+      command = arguments.shift
+
+      case command
+      when "discover"
+        Discover.call(arguments, output: output, error: error)
+      when "run"
+        junit_output = extract_option!(
+          arguments,
+          "--junit",
+          default: Run::DEFAULT_JUNIT_OUTPUT
+        )
+        arguments.shift if arguments.first == "--"
+
+        Run.call(
+          arguments,
+          junit_output: junit_output,
+          output: output,
+          error: error
+        )
+      when "version", "--version", "-v"
+        output.puts(VERSION)
+        0
+      else
+        error.puts(usage)
+        EXIT_USAGE
+      end
+    rescue ArgumentError => exception
+      error.puts(exception.message)
+      error.puts(usage)
+      EXIT_USAGE
+    end
+
+    def self.extract_option!(arguments, option, default:)
+      index = arguments.index(option)
+      return default unless index
+
+      value = arguments[index + 1]
+      if value.nil? || value.empty? || value == "--"
+        raise ArgumentError, "Missing #{option} PATH"
+      end
+
+      arguments.slice!(index, 2)
+      value
+    end
+
+    def self.usage
+      <<~USAGE
+        Usage:
+          rspec-atoms discover [RSpec arguments]
+          rspec-atoms run [--junit PATH] -- [RSpec arguments]
+          rspec-atoms version
+      USAGE
+    end
+
+    private_class_method :extract_option!, :usage
+  end
+end

data/lib/rspec_atoms/discover.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "stringio"
+require "tempfile"
+
+require_relative "discovery_formatter"
+
+module RSpecAtoms
+  module Discover
+    module_function
+
+    def call(arguments, output: $stdout, error: $stderr)
+      Tempfile.create(["rspec-atoms", ".txt"]) do |atoms_file|
+        runner_output = StringIO.new
+        RSpec.configuration.fail_if_no_examples = true
+
+        status = RSpec::Core::Runner.run(
+          rspec_arguments(arguments, atoms_file.path),
+          error,
+          runner_output
+        )
+
+        if status.zero?
+          atoms_file.rewind
+          IO.copy_stream(atoms_file, output)
+        else
+          write_runner_output(runner_output, error)
+        end
+
+        status
+      end
+    end
+
+    def rspec_arguments(arguments, atoms_path)
+      [
+        "--dry-run",
+        "--no-color",
+        "--format",
+        "RSpecAtoms::DiscoveryFormatter",
+        "--out",
+        atoms_path,
+        *arguments
+      ]
+    end
+
+    def write_runner_output(runner_output, error)
+      content = runner_output.string
+      return if content.empty?
+
+      error.write(content)
+      error.write("\n") unless content.end_with?("\n")
+    end
+  end
+end

data/lib/rspec_atoms/discovery_formatter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+require_relative "example_id"
+
+module RSpecAtoms
+  class DiscoveryFormatter
+    RSpec::Core::Formatters.register self, :example_started, :close
+
+    def initialize(output)
+      @output = output
+    end
+
+    def example_started(notification)
+      @output.puts(
+        ExampleId.normalize(notification.example.id)
+      )
+    end
+
+    def close(_notification)
+      @output.flush
+    end
+  end
+end

data/lib/rspec_atoms/example_id.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RSpecAtoms
+  module ExampleId
+    SELECTOR_PATTERN = /\[[^\]]+\]\z/
+
+    module_function
+
+    def normalize(value)
+      value.to_s.sub(/\A\.\//, "")
+    end
+
+    def file_path(value)
+      normalize(value).sub(SELECTOR_PATTERN, "")
+    end
+  end
+end

data/lib/rspec_atoms/junit_formatter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rspec_junit_formatter"
+
+require_relative "example_id"
+
+module RSpecAtoms
+  class JunitFormatter < ::RSpecJUnitFormatter
+    RSpec::Core::Formatters.register(
+      self,
+      :start,
+      :stop,
+      :dump_summary
+    )
+
+    private
+
+    def example_group_file_path_for(notification)
+      ExampleId.normalize(notification.example.id)
+    end
+
+    def classname_for(notification)
+      ExampleId
+        .file_path(notification.example.id)
+        .sub(%r{\.[^/]*\z}, "")
+        .tr("/", ".")
+        .gsub(/\A\.+|\.+\z/, "")
+    end
+  end
+end

data/lib/rspec_atoms/run.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rspec/core"
+
+require_relative "junit_formatter"
+
+module RSpecAtoms
+  module Run
+    DEFAULT_JUNIT_OUTPUT = "tmp/rspec.xml"
+
+    module_function
+
+    def call(
+      arguments,
+      junit_output: DEFAULT_JUNIT_OUTPUT,
+      output: $stdout,
+      error: $stderr
+    )
+      ensure_output_directory(junit_output)
+
+      RSpec::Core::Runner.run(
+        inject_formatters(arguments, junit_output),
+        error,
+        output
+      )
+    end
+
+    def inject_formatters(arguments, junit_output)
+      separator_index = arguments.index("--") || arguments.length
+      options = arguments[0...separator_index]
+      selectors = arguments[separator_index..] || []
+
+      [
+        *options,
+        "--format",
+        "progress",
+        "--format",
+        "RSpecAtoms::JunitFormatter",
+        "--out",
+        junit_output,
+        *selectors
+      ]
+    end
+
+    def ensure_output_directory(junit_output)
+      directory = File.dirname(junit_output)
+      return if directory == "."
+
+      FileUtils.mkdir_p(directory)
+    end
+  end
+end

data/lib/rspec_atoms/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RSpecAtoms
+  VERSION = "0.1.0"
+end

data/lib/rspec_atoms.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "rspec_atoms/version"
+require_relative "rspec_atoms/example_id"
+
+module RSpecAtoms
+end

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: rspec-atoms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jose Carbone
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: |
+  Discovers runnable RSpec examples as RSpec IDs and emits matching JUnit
+  identities for CircleCI Smarter Testing.
+email:
+- joseignaciocarbone@gmail.com
+executables:
+- rspec-atoms
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/rspec-atoms
+- lib/rspec_atoms.rb
+- lib/rspec_atoms/cli.rb
+- lib/rspec_atoms/discover.rb
+- lib/rspec_atoms/discovery_formatter.rb
+- lib/rspec_atoms/example_id.rb
+- lib/rspec_atoms/junit_formatter.rb
+- lib/rspec_atoms/run.rb
+- lib/rspec_atoms/version.rb
+homepage: https://github.com/josesei/rspec-atoms
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/josesei/rspec-atoms
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Split RSpec suites by runnable example
+test_files: []