spec_forge 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f04f0ef7fc98b027990b272a524856731de03b46f9898430f6ccfa30bc2f3fe7
-  data.tar.gz: a0130baec24c851c981aa76a4af01011e0944ece84965da37b9ad8630cc3dca3
+  metadata.gz: 658fd0830ce9179c1fe7ea880e2ed8196ccbc47bc8b244f6fc40c458ca900cca
+  data.tar.gz: 3658379f52f23ffa362ded1c50b28e052911b6602ac3a3bed02b1fd9c8ee334c
 SHA512:
-  metadata.gz: 0b933a4b603f899c5140997c0e551d86c497671ed2447088489bb3f5dbdb056bb89757bc67bd4fc72033ddede7c54df64e9eb73b64d76092c6d5dbf997c31ab9
-  data.tar.gz: 8b274025784f417bd7250f0fd716414c5511d392af4e2daabe1eb8fe1116f9416415f2b1d4c0495922fd7509b4a3b5fb648a86a4a62a6ced69b5392da906140b
+  metadata.gz: ebcdfd4e02d965049cabd1a18b7897665800dc8081149aa4554433e7083296f0121d76f4ec474b527fdd8df0da1c71170c9c10c5cff1a108f8704b7f14e7104f
+  data.tar.gz: ad3b84d27b9e7ab62dc902ad2a5d41a77670286aaba9a635ccebf5735061fa725e8d46daf62fd75562a35688d62b3dc595a597b9e38ec965f5273fdc27a2aabb

data/CHANGELOG.md

@@ -13,6 +13,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.4.0] - 12025-02-22
+
+### Added
+
+- Added support to run an individual file, spec, or expectation
+
+### Changed
+
+- Updated `everythingrb` to 0.2
+- Updated spec and factory templates
+- Improved error reporting to use SpecForge's commands instead of RSpec's
+- Updated `run` command's CLI documentation
+
+### Removed
+
+- Removed support for ActiveSupport 7.0
+
+## [0.3.2] - 12025-02-20
+
+### Changed
+
+- Moved Regex into its own Attribute class
+- Fixed Regex parsing
+
 ## [0.3.0] - 12025-02-17
 
 ### Added
@@ -64,7 +88,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial commit
 
-[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.3.0...HEAD
+[unreleased]: https://github.com/itsthedevman/spec_forge/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/itsthedevman/spec_forge/compare/v0.3.2...v0.4.0
+[0.3.2]: https://github.com/itsthedevman/spec_forge/compare/v0.3.0...v0.3.2
 [0.3.0]: https://github.com/itsthedevman/spec_forge/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/itsthedevman/spec_forge/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/itsthedevman/spec_forge/compare/a8a991c25dcbd472a5fd975e96aa223b05948618...v0.1.0

data/README.md

@@ -1,8 +1,8 @@
 # SpecForge
 
 [![Gem Version](https://badge.fury.io/rb/spec_forge.svg)](https://badge.fury.io/rb/spec_forge)
+![Ruby Version](https://img.shields.io/badge/ruby-3.3.7-ruby)
 [![Tests](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml/badge.svg)](https://github.com/itsthedevman/spec_forge/actions/workflows/main.yml)
-![Ruby Version](https://img.shields.io/badge/ruby-3.3.6-ruby)
 
 Write API tests in YAML that read like documentation:
 
@@ -12,9 +12,9 @@ user_profile:
   expectations:
   - expect:
       status: 200
-    json:
-      name: kind_of.string
-      email: /@/
+      json:
+        name: kind_of.string
+        email: /@/
 ```
 
 That's a complete test. No Ruby code, no configuration files, no HTTP client setup - just a clear description of what you're testing. Under the hood, you get all the power of RSpec's matchers, Faker's data generation, and FactoryBot's test objects.
@@ -41,24 +41,33 @@ Consider alternatives when you need:
 ## Roadmap
 
 Current development priorities:
-- [ ] Support for running individual specs
 - [ ] Array support for `json` expectations
 - [ ] Negated matchers: `matcher.not`
 - [ ] `create_list/build_list` factory strategies
 - [ ] `transform.map` support
-- [ ] Improved error handling
 - [ ] XML/HTML response handling
 - [ ] OpenAPI generation from tests
+- [x] Support for running individual specs
+- [x] Improved error handling
 
 Have a feature request? Open an issue on GitHub!
 
+## Looking for a Software Engineer?
+
+I'm currently looking for opportunities where I can tackle meaningful problems and help build reliable software while mentoring the next generation of developers. If you're looking for a senior engineer with full-stack Rails expertise and a passion for clean, maintainable code, let's talk!
+
+[bryan@itsthedevman.com](mailto:bryan@itsthedevman.com)
+
 ## Table of Contents
 
-- [Features](#features)
 - [Compatibility](#compatibility)
 - [Installation](#installation)
 - [Getting Started](#getting-started)
-- [Writing Your First Test](#writing-your-first-test)
+- [Forging Your First Test](#forging-your-first-test)
+- [Running Tests](#running-tests)
+  - [Targeting Specific Files](#targeting-specific-files)
+  - [Targeting Specific Specs](#targeting-specific-specs)
+  - [Targeting Individual Expectations](#targeting-individual-expectations)
 - [Configuration](#configuration)
   - [Basic Configuration](#basic-configuration)
   - [Framework Integration](#framework-integration)
@@ -88,12 +97,14 @@ Have a feature request? Open an issue on GitHub!
 - [How Tests Work](#how-tests-work)
 - [Contributing](#contributing)
 - [License](#license)
-- [Looking for a Software Engineer?](#looking-for-a-software-engineer)
+- [Credits](#credits)
+
+Also see: [API Documentation](https://itsthedevman.com/docs/spec_forge)
 
 ## Compatibility
 
 Currently tested on:
-- MRI Ruby 3.0+
+- MRI Ruby 3.2+
 - NixOS (see `flake.nix` for details)
 
 ## Installation
@@ -131,7 +142,7 @@ bundle exec spec_forge init
 
 This creates the `spec_forge` directory containing factory definitions, test specifications, and global configuration.
 
-## Writing Your First Test
+## Forging Your First Test
 
 Let's write a simple test to verify a user endpoint. Create a new spec file:
 
@@ -160,6 +171,63 @@ Run your tests with:
 spec_forge run
 ```
 
+Since `run` is the default command, you can just use:
+
+```bash
+spec_forge
+```
+
+## Running Tests
+
+As your test suite grows, you'll want more control over which tests to run.
+
+#### Targeting Specific Files
+
+When working on a specific feature, run tests from a single file:
+
+```bash
+spec_forge users # Runs all tests in specs/users.yml
+```
+
+#### Targeting Specific Specs
+
+Focus on a specific endpoint by running a single spec:
+
+```bash
+spec_forge users:destroy_user # Runs all expectations in the destroy_user spec
+```
+
+#### Targeting Individual Expectations
+
+You can also run individual expectations within a spec. The format depends on whether the expectation has a name:
+
+```yaml
+# specs/users.yml
+destroy_user:
+  path: /users/:id
+  method: delete
+  expectations:
+  - expect: # Unnamed expectation
+      status: 200
+  - name: "Destroys a User" # Named expectation
+    expect:
+      status: 200
+```
+
+For named expectations:
+```bash
+# Format: <file>:<spec>:'<verb> <path> - <name>'
+spec_forge users:destroy_user:'DELETE /users/:id - Destroys a User'
+```
+
+For unnamed expectations:
+```bash
+# Format: <file>:<spec>:'<verb> <path>'
+spec_forge users:destroy_user:'DELETE /users/:id'
+```
+
+**Note**: When targeting an unnamed expectation, SpecForge executes all matching expectations within that spec. This means if you have multiple unnamed expectations with the same verb and path, they will all run.
+
 ## Configuration
 
 ### Basic Configuration
@@ -393,13 +461,13 @@ list_posts:
   expectations:
   - expect:
       status: 200
-    json:
-      posts:
-        matcher.include:
-        - author:
-            id: variables.author.id
-            name: variables.author.name
-          category: variables.category_name
+      json:
+        posts:
+          matcher.include:
+          - author:
+              id: variables.author.id
+              name: variables.author.name
+            category: variables.category_name
 ```
 
 ### Transformations
@@ -644,6 +712,10 @@ Please note that this project is released with a [Contributor Code of Conduct](C
 
 The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
 
-## Looking for a Software Engineer?
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
+
+## Credits
 
-I'm looking for work! Please send serious enquiries to bryan@itsthedevman.com
+- Author: Bryan "itsthedevman"

data/lib/spec_forge/attribute/literal.rb

@@ -3,8 +3,6 @@
 module SpecForge
   class Attribute
     class Literal < Attribute
-      REGEX_REGEX = /^\/.+\/[mnix\s]*$/i
-
       attr_reader :value
 
       #
@@ -14,18 +12,10 @@ module SpecForge
       def initialize(input)
         super
 
-        @value =
-          case input
-          when REGEX_REGEX
-            Regexp.new(input)
-          else
-            input
-          end
+        @value = input
       end
 
-      def resolve
-        @value
-      end
+      alias_method :resolve, :value
     end
   end
 end

data/lib/spec_forge/attribute/regex.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    class Regex < Attribute
+      KEYWORD_REGEX = /^\/(?<content>[\s\S]+)\/(?<flags>[mnix\s]*)$/i
+
+      attr_reader :value
+
+      def initialize(input)
+        super
+
+        @value = parse_regex(input)
+      end
+
+      def resolve
+        @value
+      end
+
+      private
+
+      def parse_regex(input)
+        match = input.match(KEYWORD_REGEX)
+        captures = match.named_captures.symbolize_keys
+
+        flags = parse_flags(captures[:flags])
+        Regexp.new(captures[:content], flags)
+      end
+
+      # I would've used Regexp.new(string, string), but it raises when "n" is provided as a flag
+      def parse_flags(flags)
+        return 0 if flags.blank?
+
+        flags.strip.chars.reduce(0) do |options, flag|
+          case flag
+          when "i"
+            options | Regexp::IGNORECASE
+          when "m"
+            options | Regexp::MULTILINE
+          when "x"
+            options | Regexp::EXTENDED
+          when "n"
+            options | Regexp::NOENCODING
+          else
+            raise ArgumentError, "unknown regexp option: #{flag}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute.rb

@@ -10,6 +10,7 @@ require_relative "attribute/factory"
 require_relative "attribute/faker"
 require_relative "attribute/literal"
 require_relative "attribute/matcher"
+require_relative "attribute/regex"
 require_relative "attribute/resolvable_array"
 require_relative "attribute/resolvable_hash"
 require_relative "attribute/transform"
@@ -81,6 +82,8 @@ module SpecForge
         Matcher.new(string)
       when Factory::KEYWORD_REGEX
         Factory.new(string)
+      when Regex::KEYWORD_REGEX
+        Regex.new(string)
       else
         Literal.new(string)
       end

data/lib/spec_forge/backtrace_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Used internally by RSpec
+  # This class handles formatting backtraces, hence the name ;)
+  #
+  module BacktraceFormatter
+    def self.formatter
+      @formatter ||= RSpec::Core::BacktraceFormatter.new
+    end
+
+    def self.backtrace_line(line)
+      formatter.backtrace_line(line)
+    end
+
+    def self.format_backtrace(backtrace, example_metadata)
+      backtrace = SpecForge.backtrace_cleaner.clean(backtrace)
+
+      location = example_metadata[:example_group][:location]
+      line_number = example_metadata[:example_group][:line_number]
+
+      # Add the yaml location to the front so it's the first thing people see
+      ["#{location}:#{line_number}"] + backtrace
+    end
+  end
+end

data/lib/spec_forge/cli/new.rb

@@ -38,123 +38,33 @@ module SpecForge
       private
 
       def create_new_spec(name)
-        actions.create_file(
+        actions.template(
+          "new_spec.tt",
           SpecForge.forge.join("specs", "#{name}.yml"),
-          generate_spec(name)
+          context: Proxy.new(name).call
         )
       end
 
       def create_new_factory(name)
-        actions.create_file(
+        actions.template(
+          "new_factory.tt",
           SpecForge.forge.join("factories", "#{name}.yml"),
-          generate_factory(name)
+          context: Proxy.new(name).call
         )
       end
 
-      def generate_spec(name)
-        plural_name = name.pluralize
-        singular_name = name.singularize
+      class Proxy
+        attr_reader :original_name, :singular_name, :plural_name
 
-        base_spec = {url: ""}
-        base_constraint = {expect: {status: 200}}
-
-        hash = {
-          ##################################################
-          "index_#{plural_name}" => base_spec.merge(
-            url: "/#{plural_name}",
-            expectations: [base_constraint]
-          ),
-          ##################################################
-          "show_#{singular_name}" => base_spec.merge(
-            url: "/#{plural_name}/{id}",
-            expectations: [
-              base_constraint.merge(expect: {status: 404}),
-              base_constraint.deep_merge(
-                query: {id: 1},
-                expect: {
-                  json: {
-                    name: "kind_of.string",
-                    email: /\w+@example\.com/i
-                  }
-                }
-              )
-            ]
-          ),
-          ##################################################
-          "create_#{singular_name}" => base_spec.merge(
-            url: "/#{plural_name}",
-            method: "post",
-            expectations: [
-              base_constraint.merge(expect: {status: 400}),
-              base_constraint.deep_merge(
-                variables: {
-                  name: "faker.name.name",
-                  role: "user"
-                },
-                body: {name: "variables.name"},
-                expect: {
-                  json: {name: "variables.name", role: "variables.role"}
-                }
-              )
-            ]
-          ),
-          ##################################################
-          "update_#{singular_name}" => base_spec.merge(
-            url: "/#{plural_name}/{id}",
-            method: "patch",
-            query: {id: 1},
-            variables: {
-              number: {
-                "faker.number.between" => {from: 100_000, to: 999_999}
-              }
-            },
-            expectations: [
-              base_constraint.deep_merge(
-                body: {number: "variables.number"},
-                expect: {
-                  json: {name: "kind_of.string", number: "kind_of.integer"}
-                }
-              )
-            ]
-          ),
-          ##################################################
-          "destroy_#{singular_name}" => base_spec.merge(
-            url: "/#{plural_name}/{id}",
-            method: "delete",
-            query: {id: 1},
-            expectations: [
-              base_constraint
-            ]
-          )
-        }
-
-        generate_yaml(hash)
-      end
-
-      def generate_factory(name)
-        singular_name = name.singularize
-
-        hash = {
-          singular_name => {
-            class: singular_name.titleize,
-            attributes: {
-              attribute: "value"
-            }
-          }
-        }
-
-        generate_yaml(hash)
-      end
-
-      def generate_yaml(hash)
-        result = hash.deep_stringify_keys.join_map("\n") do |key, value|
-          {key => value}.to_yaml
-            .sub!("---\n", "")
-            .gsub("!ruby/regexp ", "")
+        def initialize(name)
+          @original_name = name
+          @plural_name = name.pluralize
+          @singular_name = name.singularize
         end
 
-        result.delete!("\"")
-        result
+        def call
+          binding
+        end
       end
     end
   end

data/lib/spec_forge/cli/run.rb

@@ -4,13 +4,63 @@ module SpecForge
   class CLI
     class Run < Command
       command_name "run"
-      syntax "run"
-      summary "Runs all specs"
+      syntax "run [target]"
+
+      summary "Runs specs loaded from spec_forge/specs/"
+      description "Runs specs loaded from spec_forge/specs/. The optional target argument allows running specific files, specs, or expectations."
+
+      example "spec_forge run",
+        "Run all specs in spec_forge/specs/"
+
+      example "spec_forge run users",
+        "Run all specs in users.yml"
+
+      example "spec_forge run users:create_user",
+        "Run all expectations in the create_user spec"
+
+      example "spec_forge run users:create_user:\"POST /users\"",
+        "Run expectations matching POST /users"
+
+      example "spec_forge run users:create_user:\"POST /users - Create Admin\"",
+        "Run the specific expectation named \"Create Admin\""
 
       # option "-n", "--no-docs", "Do not generate OpenAPI documentation on completion"
 
       def call
-        SpecForge.run
+        return SpecForge.run if arguments.blank?
+
+        # spec_forge users:show_user
+        filter = extract_filter(arguments.first)
+
+        # Filter and run the specs
+        SpecForge.run(**filter)
+      end
+
+      private
+
+      #
+      # The input can be
+      #
+      #   "<file_name>" for a file
+      #     Example: "users"
+      #
+      #   "<file_name>:<spec_name>" for a single spec
+      #     Example: "users:show_user"
+      #
+      #   "<file_name:<spec_name>:'<verb> <path> - <?name>'" for a single expectation
+      #     Example:
+      #       "users:show_user:'GET /users/:id'"
+      #     Example with name:
+      #       "users:show_user:'GET /users/:id - Returns 404 due to missing user'"
+      #
+      def extract_filter(input)
+        # Note: Only split 3 because the expectation name can have colons in them.
+        file_name, spec_name, expectation_name = input.split(":", 3).map(&:strip)
+
+        # Remove the quotes
+        expectation_name.gsub!(/^['"]|['"]$/, "") if expectation_name.present?
+
+        {file_name:, spec_name:, expectation_name:}
       end
     end
   end

data/lib/spec_forge/configuration.rb

@@ -30,6 +30,9 @@ module SpecForge
     def initialize
       config = Normalizer.default_configuration
 
+      # Allows me to modify the error backtrace reporting within rspec
+      RSpec.configuration.instance_variable_set(:@backtrace_formatter, BacktraceFormatter)
+
       config[:base_url] = "http://localhost:3000"
       config[:factories] = Factories.new
       config[:specs] = RSpec.configuration

data/lib/spec_forge/core_ext/rspec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Core
+    module Notifications
+      #
+      # I did attempt to do this without monkey patching
+      # Getting around the `rspec` word was making it difficult
+      #
+      class SummaryNotification
+        # Customizes RSpec's failure output to:
+        # 1. Use 'spec_forge' instead of 'rspec' for rerun commands
+        # 2. Remove line numbers since SpecForge uses dynamic spec generation
+        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
+
+        def colorized_rerun_commands(colorizer)
+          # Updating these at this point fixes the re-run for some failures - it depends
+          failed_examples.each do |example|
+            metadata = example.metadata[:example_group]
+
+            # I might've uncovered an inconsistency here
+            # When multiple specs fail, it appears that the rerun_commands will use
+            # :rerun_file_path from the example's metadata.
+            # But when a single spec is ran and fails, it's using :location.
+            example.metadata[:location] = metadata[:rerun_file_path]
+            example.metadata[:line_number] = metadata[:line_number]
+          end
+
+          og_colorized_rerun_commands.gsub(/rspec/i, "spec_forge")
+            .gsub(/\[[\d:]+\]/, "")
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/core_ext.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Dir[File.expand_path("core_ext/*.rb", __dir__)].sort.each do |path|
+  require path
+end

data/lib/spec_forge/factory.rb

@@ -5,32 +5,30 @@ module SpecForge
     #
     # Loads the factories from their yml files and registers them with FactoryBot
     #
-    # @param path [String, Path] The base path where the factories directory are located
-    #
-    def self.load_and_register(base_path)
+    def self.load_and_register
       if SpecForge.configuration.factories.paths?
         FactoryBot.definition_file_paths = SpecForge.configuration.factories.paths
       end
 
       FactoryBot.find_definitions if SpecForge.configuration.factories.auto_discover?
 
-      factories = load_from_path(base_path.join("factories", "**/*.yml"))
+      factories = load_from_files
       factories.each(&:register)
     end
 
     #
-    # Loads any factories defined in the path. A single file can contain one or more factories
-    #
-    # @param path [String, Path] The path where the factories are located
+    # Loads any factories defined in the factories. A single file can contain one or more factories
     #
     # @return [Array<Factory>] An array of factories that were loaded.
     #   Note: This factories have not been registered with FactoryBot.
     #   See #register
     #
-    def self.load_from_path(path)
+    def self.load_from_files
+      path = SpecForge.forge.join("factories", "**/*.yml")
+
       factories = []
 
-      Dir[path].map do |file_path|
+      Dir[path].each do |file_path|
         hash = YAML.load_file(file_path).deep_symbolize_keys
 
         hash.each do |factory_name, factory_hash|

data/lib/spec_forge/runner.rb

@@ -23,6 +23,9 @@ module SpecForge
           spec_forge.expectations.each do |expectation|
             # Define the example group
             describe(expectation.name) do
+              # Set up the class metadata for error reporting
+              runner_forge.set_group_metadata(self, spec_forge, expectation)
+
               constraints = expectation.constraints
 
               let!(:expected_status) { constraints.status.resolve }
@@ -31,6 +34,9 @@ module SpecForge
               before do
                 # Ensure all variables are called and resolved, in case they are not referenced
                 expectation.variables.resolve
+
+                # Set up the example metadata for error reporting
+                runner_forge.set_example_metadata(spec_forge, expectation)
               end
 
               subject(:response) { expectation.http_client.call }
@@ -54,9 +60,31 @@ module SpecForge
         end
       end
 
+      # @private
       def handle_debug(...)
         DebugProxy.new(...).call
       end
+
+      # @private
+      def set_group_metadata(context, spec, expectation)
+        metadata = {
+          file_path: spec.file_path,
+          absolute_file_path: spec.file_path,
+          line_number: spec.line_number,
+          location: spec.file_path,
+          rerun_file_path: "#{spec.file_name}:#{spec.name}:\"#{expectation.name}\""
+        }
+
+        context.metadata.merge!(metadata)
+      end
+
+      # @private
+      def set_example_metadata(spec, expectation)
+        # This is needed when an error raises in an example
+        metadata = {location: "#{spec.file_path}:#{spec.line_number}"}
+
+        RSpec.current_example.metadata.merge!(metadata)
+      end
     end
 
     ################################################################################################

data/lib/spec_forge/spec/expectation/constraint.rb

@@ -26,8 +26,11 @@ module SpecForge
         def normalize_hash(hash)
           hash =
             hash.transform_values do |attribute|
-              if attribute.is_a?(Attribute::Literal)
-                normalize_literal(attribute.value)
+              case attribute
+              when Attribute::Regex
+                Attribute.from("matcher.match" => attribute.resolve)
+              when Attribute::Literal
+                Attribute.from("matcher.eq" => attribute.resolve)
               else
                 attribute
               end
@@ -35,14 +38,6 @@ module SpecForge
 
           Attribute.from(hash)
         end
-
-        def normalize_literal(value)
-          if value.is_a?(Regexp)
-            Attribute.from("matcher.match" => value)
-          else
-            Attribute.from("matcher.eq" => value)
-          end
-        end
       end
     end
   end

data/lib/spec_forge/spec.rb

@@ -5,31 +5,49 @@ require_relative "spec/expectation"
 module SpecForge
   class Spec
     #
-    # Loads the specs from their yml files and defines them with the test runner
+    # Loads and defines specs with the runner. Specs can be filtered using the optional parameters
     #
-    # @param path [String, Path] The base path where the specs directory is located
+    # @param file_name [String, nil] The name of the file without the extension.
+    # @param spec_name [String, nil] The name of the spec in a yaml file
+    # @param expectation_name [String, nil] The name of the expectation for a spec.
     #
-    def self.load_and_define(base_path)
-      specs = load_from_path(base_path.join("specs", "**/*.yml"))
+    # @return [Array<Spec>]
+    #
+    def self.load_and_define(file_name: nil, spec_name: nil, expectation_name: nil)
+      specs = load_from_files
+
+      filter_specs(specs, file_name:, spec_name:, expectation_name:)
+
+      # Announce if we're using a filter
+      if file_name
+        filter = {file_name:, spec_name:, expectation_name:}.delete_if { |k, v| v.blank? }
+        filter.stringify_keys!
+        puts "Using filter: #{filter}"
+      end
+
       specs.each(&:define)
     end
 
     #
-    # Loads any specs defined in the path. A single file can contain one or more specs
-    #
-    # @param path [String, Path] The path where the specs are located
+    # Loads any specs defined in the spec files. A single file can contain one or more specs
     #
     # @return [Array<Spec>] An array of specs that were loaded.
     #
-    def self.load_from_path(path)
+    def self.load_from_files
+      path = SpecForge.forge.join("specs")
       specs = []
 
-      Dir[path].map do |file_path|
-        hash = YAML.load_file(file_path).deep_symbolize_keys
+      Dir[path.join("**/*.yml")].each do |file_path|
+        content = File.read(file_path)
+        hash = YAML.load(content).deep_symbolize_keys
 
         hash.each do |spec_name, spec_hash|
-          spec_hash[:name] = spec_name
+          line_number = content.lines.index { |line| line.start_with?("#{spec_name}:") }
+
+          spec_hash[:name] = spec_name.to_s
           spec_hash[:file_path] = file_path
+          spec_hash[:file_name] = file_path.delete_prefix("#{path}/").delete_suffix(".yml")
+          spec_hash[:line_number] = line_number ? line_number + 1 : -1
 
           specs << new(**spec_hash)
         end
@@ -38,11 +56,34 @@ module SpecForge
       specs
     end
 
+    # @private
+    def self.filter_specs(specs, file_name: nil, spec_name: nil, expectation_name: nil)
+      # Guard against invalid partial filters
+      if expectation_name && spec_name.blank?
+        raise ArgumentError, "The spec's name is required when filtering by an expectation's name"
+      end
+
+      if spec_name && file_name.blank?
+        raise ArgumentError, "The spec's filename is required when filtering by a spec's name"
+      end
+
+      specs.select! { |spec| spec.file_name == file_name } if file_name
+      specs.select! { |spec| spec.name == spec_name } if spec_name
+
+      if expectation_name
+        specs.each do |spec|
+          spec.expectations.select! { |expectation| expectation.name == expectation_name }
+        end
+      end
+
+      specs
+    end
+
     ############################################################################
 
     attr_predicate :debug
 
-    attr_reader :name, :file_path, :expectations
+    attr_reader :name, :file_path, :file_name, :line_number, :expectations
 
     #
     # Creates a Spec based on the input
@@ -52,9 +93,11 @@ module SpecForge
     # @param **input [Hash] Any attributes related to the spec, including expectations
     #   See Normalizer::Spec
     #
-    def initialize(name:, file_path:, **input)
+    def initialize(name:, file_path:, file_name:, line_number:, **input)
       @name = name
       @file_path = file_path
+      @file_name = file_name
+      @line_number = line_number
 
       input = Normalizer.normalize_spec!(input)
 

data/lib/spec_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpecForge
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/spec_forge.rb

@@ -17,8 +17,10 @@ require "thor"
 require "yaml"
 
 require_relative "spec_forge/attribute"
+require_relative "spec_forge/backtrace_formatter"
 require_relative "spec_forge/cli"
 require_relative "spec_forge/configuration"
+require_relative "spec_forge/core_ext"
 require_relative "spec_forge/error"
 require_relative "spec_forge/factory"
 require_relative "spec_forge/http"
@@ -34,15 +36,21 @@ module SpecForge
   #
   # @param path [String] The file path that contains factories and specs
   #
-  def self.run(path = SpecForge.forge)
+  def self.run(file_name: nil, spec_name: nil, expectation_name: nil)
+    path = SpecForge.forge
+
+    # Initialize
     forge_helper = path.join("forge_helper.rb")
     require_relative forge_helper if File.exist?(forge_helper)
 
+    # Validate
     configuration.validate
 
-    Factory.load_and_register(path)
-    Spec.load_and_define(path)
+    # Prepare
+    Factory.load_and_register
+    Spec.load_and_define(file_name:, spec_name:, expectation_name:)
 
+    # Run
     Runner.run
   end
 

data/lib/templates/new_factory.tt

@@ -0,0 +1,4 @@
+<%= original_name %>:
+  class: <%= singular_name.titleize %>
+  attributes:
+    active: true

data/lib/templates/new_spec.tt

@@ -0,0 +1,43 @@
+index_<%= plural_name %>:
+  url: /<%= plural_name %>
+  expectations:
+  - expect:
+      status: 200
+
+show_<%= singular_name %>:
+  url: /<%= plural_name %>/{id}
+  query:
+    id: 1
+  expectations:
+  - expect:
+      status: 200
+
+create_<%= singular_name %>:
+  url: /<%= plural_name %>
+  method: post
+  body:
+    name: faker.name.name
+    email: faker.internet.email
+  expectations:
+  - expect:
+      status: 200
+
+update_<%= singular_name %>:
+  url: /<%= plural_name %>/{id}
+  method: patch
+  query:
+    id: 1
+  body:
+    name:
+  expectations:
+  - expect:
+      status: 200
+
+destroy_<%= singular_name %>:
+  url: /<%= plural_name %>/{id}
+  method: delete
+  query:
+    id: 1
+  expectations:
+  - expect:
+      status: 200

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spec_forge
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-17 00:00:00.000000000 Z
+date: 2025-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: commander
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: factory_bot
   requirement: !ruby/object:Gem::Requirement
@@ -166,11 +166,13 @@ files:
 - lib/spec_forge/attribute/literal.rb
 - lib/spec_forge/attribute/matcher.rb
 - lib/spec_forge/attribute/parameterized.rb
+- lib/spec_forge/attribute/regex.rb
 - lib/spec_forge/attribute/resolvable.rb
 - lib/spec_forge/attribute/resolvable_array.rb
 - lib/spec_forge/attribute/resolvable_hash.rb
 - lib/spec_forge/attribute/transform.rb
 - lib/spec_forge/attribute/variable.rb
+- lib/spec_forge/backtrace_formatter.rb
 - lib/spec_forge/cli.rb
 - lib/spec_forge/cli/actions.rb
 - lib/spec_forge/cli/command.rb
@@ -178,6 +180,8 @@ files:
 - lib/spec_forge/cli/new.rb
 - lib/spec_forge/cli/run.rb
 - lib/spec_forge/configuration.rb
+- lib/spec_forge/core_ext.rb
+- lib/spec_forge/core_ext/rspec.rb
 - lib/spec_forge/error.rb
 - lib/spec_forge/factory.rb
 - lib/spec_forge/http.rb
@@ -199,6 +203,8 @@ files:
 - lib/spec_forge/type.rb
 - lib/spec_forge/version.rb
 - lib/templates/forge_helper.tt
+- lib/templates/new_factory.tt
+- lib/templates/new_spec.tt
 - spec_forge/factories/user.yml
 - spec_forge/forge_helper.rb
 - spec_forge/specs/users.yml