state_machines-yard 0.0.1 → 0.1.0

data/test/handlers/event_test.rb

@@ -0,0 +1,84 @@
+require 'test_helper'
+
+class EventHandlerTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_event_handler_registers_events
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          # Ignition event
+          event :ignite do
+            transition parked: :idling
+          end
+
+          # Drive event
+          event :drive do
+            transition idling: :moving
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check for methods that should be generated for events
+    can_ignite_method = YARD::Registry.at('Vehicle#can_ignite?')
+    refute_nil can_ignite_method, "can_ignite? method should be registered"
+    assert_match(/Checks whether :ignite can be fired/, can_ignite_method.docstring.to_s)
+    
+    ignite_method = YARD::Registry.at('Vehicle#ignite')
+    refute_nil ignite_method, "ignite method should be registered"
+    assert_match(/Fires the :ignite event/, ignite_method.docstring.to_s)
+    
+    ignite_bang_method = YARD::Registry.at('Vehicle#ignite!')
+    refute_nil ignite_bang_method, "ignite! method should be registered"
+    assert_match(/Fires the :ignite event, raising an exception if it fails/, ignite_bang_method.docstring.to_s)
+    
+    ignite_transition_method = YARD::Registry.at('Vehicle#ignite_transition')
+    refute_nil ignite_transition_method, "ignite_transition method should be registered"
+    assert_match(/Gets the next transition that would be performed if :ignite were to be fired/, ignite_transition_method.docstring.to_s)
+  end
+
+  def test_event_handler_with_multiple_events
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status do
+          # These are the possible events
+          event :ignite, :drive, :park
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check for methods that should be generated for each event
+    %w(ignite drive park).each do |event|
+      can_method = YARD::Registry.at("Vehicle#can_#{event}?")
+      refute_nil can_method, "can_#{event}? method should be registered"
+      
+      event_method = YARD::Registry.at("Vehicle##{event}")
+      refute_nil event_method, "#{event} method should be registered"
+      
+      bang_method = YARD::Registry.at("Vehicle##{event}!")
+      refute_nil bang_method, "#{event}! method should be registered"
+      
+      transition_method = YARD::Registry.at("Vehicle##{event}_transition")
+      refute_nil transition_method, "#{event}_transition method should be registered"
+    end
+  end
+end

data/test/handlers/machine_test.rb

@@ -0,0 +1,72 @@
+require 'test_helper'
+
+class MachineHandlerTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_machine_handler_registers_state_machine
+    code = <<-RUBY
+      class Vehicle
+        # This is a state machine for vehicle status
+        state_machine :status, initial: :parked do
+          # States and events
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    assert has_attribute?(vehicle_class, 'state_machines'), "Vehicle class should have state_machines attribute"
+    assert_equal 1, vehicle_class['state_machines'].size, "Vehicle should have one state machine"
+    assert vehicle_class['state_machines'].key?(:status), "Vehicle should have a status state machine"
+    
+    machine = vehicle_class['state_machines'][:status]
+    assert_equal :status, machine[:name], "Machine name should be :status"
+    assert_equal "This is a state machine for vehicle status", machine[:description], "Machine description should match"
+  end
+
+  def test_machine_handler_with_default_name
+    code = <<-RUBY
+      class Vehicle
+        # Default state machine
+        state_machine do
+          # States and events
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    assert vehicle_class['state_machines'].key?(:state), "Vehicle should have a default state machine"
+  end
+
+  def test_machine_handler_with_options
+    code = <<-RUBY
+      class Vehicle
+        # State machine with options
+        state_machine :status, initial: :parked, namespace: 'vehicle', attribute: :vehicle_status do
+          # States and events
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    machine = vehicle_class['state_machines'][:status]
+    refute_nil machine, "Status state machine should be registered"
+  end
+end

data/test/handlers/state_test.rb

@@ -0,0 +1,66 @@
+require 'test_helper'
+
+class StateHandlerTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_state_handler_registers_states
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          # Parked state
+          state :parked do
+            # State behavior
+          end
+
+          # Moving state
+          state :moving
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check for methods that should be generated for states
+    parked_method = YARD::Registry.at('Vehicle#parked?')
+    refute_nil parked_method, "parked? method should be registered"
+    assert_equal "Checks whether :parked is the current state.", parked_method.docstring.to_s
+    
+    moving_method = YARD::Registry.at('Vehicle#moving?')
+    refute_nil moving_method, "moving? method should be registered"
+    assert_equal "Checks whether :moving is the current state.", moving_method.docstring.to_s
+  end
+
+  def test_state_handler_with_multiple_states
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status do
+          # These are the possible states
+          state :parked, :idling, :moving
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check for methods that should be generated for each state
+    %w(parked idling moving).each do |state|
+      method = YARD::Registry.at("Vehicle##{state}?")
+      refute_nil method, "#{state}? method should be registered"
+      assert_equal "Checks whether :#{state} is the current state.", method.docstring.to_s
+    end
+  end
+end

data/test/handlers/transition_test.rb

@@ -0,0 +1,108 @@
+require 'test_helper'
+
+class TransitionHandlerTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_transition_handler_in_event_context
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          event :ignite do
+            # Transition from parked to idling
+            transition parked: :idling
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check for transitions documentation through the event methods
+    ignite_method = YARD::Registry.at('Vehicle#ignite')
+    refute_nil ignite_method, "ignite method should be registered"
+  end
+
+  def test_transition_handler_with_multiple_states
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          event :drive do
+            # Transition from multiple states
+            transition [:idling, :parked] => :moving
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # The drive method should be registered
+    drive_method = YARD::Registry.at('Vehicle#drive')
+    refute_nil drive_method, "drive method should be registered"
+  end
+
+  def test_transition_handler_with_conditional
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          event :drive do
+            # Transition with a conditional
+            transition parked: :moving, if: :engine_started?
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # The drive method should be registered despite the conditional
+    drive_method = YARD::Registry.at('Vehicle#drive')
+    refute_nil drive_method, "drive method should be registered"
+  end
+
+  def test_transition_handler_with_special_matchers
+    code = <<-RUBY
+      class Vehicle
+        state_machine :status, initial: :parked do
+          event :repair do
+            # Use 'all' matcher
+            transition any => :parked
+          end
+          
+          event :maintain do
+            # Use 'same' matcher
+            transition all => same
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Both methods should be registered
+    repair_method = YARD::Registry.at('Vehicle#repair')
+    refute_nil repair_method, "repair method should be registered"
+    
+    maintain_method = YARD::Registry.at('Vehicle#maintain')
+    refute_nil maintain_method, "maintain method should be registered"
+  end
+end

data/test/integration_test.rb

@@ -0,0 +1,152 @@
+require 'test_helper'
+
+class IntegrationTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_full_documentation_integration
+    # Create a more complex class with state machine
+    code = <<-RUBY
+      # A vehicle class representing automobiles
+      # @author Test Author
+      class Vehicle
+        # The vehicle's engine state
+        # @return [Boolean] true if the engine is on, false otherwise
+        attr_accessor :engine_on
+        # Status state machine tracks the operational status of the vehicle
+        state_machine :status, initial: :parked do
+          description "Controls the vehicle's operational status"
+          
+          # Parked state - vehicle is not moving and can be started
+          state :parked do
+            description "Vehicle is stopped and secured"
+          end
+          
+          # Idling state - engine is running but vehicle is not moving
+          state :idling do
+            description "Engine is running but vehicle is stationary"
+          end
+          
+          # Moving state - vehicle is in motion
+          state :moving do
+            description "Vehicle is in motion"
+          end
+          
+          # Stalled state - vehicle has encountered a problem
+          state :stalled do
+            description "Vehicle has encountered a problem"
+          end
+          
+          # Ignition event - turns on the engine
+          event :ignite do
+            description "Starts the vehicle's engine"
+            transition parked: :idling
+          end
+          
+          # Drive event - puts vehicle in motion
+          event :drive do
+            description "Puts the vehicle in motion"
+            transition idling: :moving
+          end
+          
+          # Stop event - brings vehicle to a stop
+          event :stop do
+            description "Stops the vehicle"
+            transition moving: :idling
+          end
+          
+          # Park event - secure the vehicle
+          event :park do
+            description "Secures the vehicle"
+            transition idling: :parked
+          end
+          
+          # Stall event - unexpected problem
+          event :stall do
+            description "Vehicle encountered a problem"
+            transition [:idling, :moving] => :stalled
+          end
+          
+          # Repair event - fix the stalled vehicle
+          event :repair do
+            description "Fix vehicle issues"
+            transition stalled: :parked
+          end
+        end
+        
+        # Second state machine for the gear position
+        state_machine :gear, initial: :neutral do
+          state :neutral
+          state :first
+          state :second
+          state :third
+          
+          event :shift_up do
+            transition neutral: :first, first: :second, second: :third
+          end
+          
+          event :shift_down do
+            transition third: :second, second: :first, first: :neutral
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    # Verify YARD Registry
+    vehicle_class = YARD::Registry.at('Vehicle')
+    refute_nil vehicle_class, "Vehicle class should be registered"
+    
+    # Check state machines attribute exists
+    assert has_attribute?(vehicle_class, 'state_machines'), "Vehicle class should have state_machines attribute"
+    assert_equal 2, vehicle_class['state_machines'].size, "Vehicle should have two state machines"
+    
+    # Check both state machines exist
+    assert vehicle_class['state_machines'].key?(:status), "Vehicle should have a status state machine"
+    assert vehicle_class['state_machines'].key?(:gear), "Vehicle should have a gear state machine"
+    
+    # Check state methods
+    %w(parked? idling? moving? stalled? neutral? first? second? third?).each do |method_name|
+      method = YARD::Registry.at("Vehicle##{method_name}")
+      refute_nil method, "#{method_name} method should be registered"
+    end
+    
+    # Check event methods for status machine
+    %w(ignite drive stop park stall repair).each do |event|
+      method = YARD::Registry.at("Vehicle##{event}")
+      refute_nil method, "#{event} method should be registered"
+      bang_method = YARD::Registry.at("Vehicle##{event}!")
+      refute_nil bang_method, "#{event}! method should be registered"
+    end
+    
+    # Check event methods for gear machine
+    %w(shift_up shift_down).each do |event|
+      method = YARD::Registry.at("Vehicle##{event}")
+      refute_nil method, "#{event} method should be registered"
+      bang_method = YARD::Registry.at("Vehicle##{event}!")
+      refute_nil bang_method, "#{event}! method should be registered"
+    end
+    
+    # Check attribute-related methods
+    status_method = YARD::Registry.at("Vehicle#status")
+    refute_nil status_method, "status method should be registered"
+
+    status_events_method = YARD::Registry.at("Vehicle#status_events")
+    refute_nil status_events_method, "status_events method should be registered"
+    
+    # Generate documentation
+    YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
+    
+    # Check if the HTML file was generated
+    html_file = File.join(@yard_dir, 'Vehicle.html')
+    assert File.exist?(html_file), "HTML file for Vehicle should exist"
+  end
+end

data/test/templates_test.rb

@@ -0,0 +1,72 @@
+require 'test_helper'
+require 'nokogiri'
+
+class TemplatesTest < Minitest::Test
+  include TestHelpers
+
+  def setup
+    setup_yard
+  end
+
+  def teardown
+    cleanup_yard
+  end
+
+  def test_html_template_rendering
+    # Create a sample class with a state machine
+    code = <<-RUBY
+      # A vehicle class
+      # @author Test Author
+      class Vehicle
+        # This is a state machine for vehicle status
+        state_machine :status, initial: :parked do
+          state :parked
+          state :idling
+          state :moving
+          
+          event :ignite do
+            transition parked: :idling
+          end
+          
+          event :drive do
+            transition idling: :moving
+          end
+          
+          event :park do
+            transition moving: :parked
+          end
+        end
+      end
+    RUBY
+
+    parse_code(code)
+    
+    # Generate documentation
+    options = YARD::CLI::YardocOptions.new
+    options.files = []
+    options.output = @yard_dir
+    
+    YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
+    
+    # Check if the HTML file was generated
+    html_file = File.join(@yard_dir, 'Vehicle.html')
+    assert File.exist?(html_file), "HTML file for Vehicle should exist"
+    
+    # Parse the HTML and check for state machine content
+    html = File.read(html_file)
+    doc = Nokogiri::HTML(html)
+    
+    # Check for state machine section
+    state_machines_section = doc.at_css('h2:contains("State Machines")')
+    refute_nil state_machines_section, "State Machines section should exist in the HTML"
+    
+    # Check for status machine
+    status_machine = doc.at_css('h3:contains("status")')
+    refute_nil status_machine, "Status machine heading should exist in the HTML"
+    
+    # Check for description
+    description = status_machine.next_element
+    refute_nil description, "Machine description should exist"
+    assert_equal "This is a state machine for vehicle status", description.text.strip
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,37 @@
+require 'minitest/autorun'
+require 'yard'
+require 'state_machines'
+require 'state_machines/yard'
+require 'state_machines/graphviz'
+require 'nokogiri'
+require 'fileutils'
+
+# Helper module for tests
+module TestHelpers
+  # Create a temporary directory for YARD outputs
+  def setup_yard
+    @yard_dir = File.expand_path('../tmp/yard', __dir__)
+    FileUtils.rm_rf(@yard_dir) if Dir.exist?(@yard_dir)
+    FileUtils.mkdir_p(@yard_dir)
+    YARD::Registry.clear
+    # Register our handlers
+    YARD::Tags::Library.define_tag("State Machines", :state_machines)
+  end
+
+  # Parse the given code with YARD
+  def parse_code(code)
+    YARD.parse_string(code)
+    YARD::Registry.load
+  end
+
+  # Clean up after test
+  def cleanup_yard
+    FileUtils.rm_rf(@yard_dir) if Dir.exist?(@yard_dir)
+    YARD::Registry.clear
+  end
+  
+  # Helper method to check if registry object has attribute
+  def has_attribute?(obj, name)
+    obj.respond_to?(:[]) && obj[name] != nil
+  end
+end