state_machines-yard 0.0.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/.github/workflows/ci.yml +32 -0
- data/.github/workflows/release.yml +18 -0
- data/.release-please-manifest.json +3 -0
- data/.rubocop.yml +38 -0
- data/CHANGELOG.md +44 -0
- data/Gemfile +13 -0
- data/LICENSE.txt +1 -1
- data/README.md +50 -1
- data/Rakefile +29 -0
- data/lib/state_machines/yard/description.rb +74 -0
- data/lib/state_machines/yard/handlers/base.rb +122 -21
- data/lib/state_machines/yard/handlers/callback.rb +96 -0
- data/lib/state_machines/yard/handlers/event.rb +20 -11
- data/lib/state_machines/yard/handlers/machine.rb +263 -241
- data/lib/state_machines/yard/handlers/requirements.rb +92 -0
- data/lib/state_machines/yard/handlers/state.rb +20 -11
- data/lib/state_machines/yard/handlers/transition.rb +26 -31
- data/lib/state_machines/yard/handlers.rb +4 -6
- data/lib/state_machines/yard/renderer.rb +62 -0
- data/lib/state_machines/yard/templates/default/class/html/setup.rb +14 -7
- data/lib/state_machines/yard/templates/default/class/html/state_machines.erb +33 -0
- data/lib/state_machines/yard/templates.rb +2 -0
- data/lib/state_machines/yard/version.rb +3 -1
- data/lib/state_machines/yard.rb +15 -4
- data/release-please-config.json +11 -0
- data/state_machines-yard.gemspec +19 -11
- data/test/description_test.rb +99 -0
- data/test/handlers/base_test.rb +83 -0
- data/test/handlers/callback_test.rb +137 -0
- data/test/handlers/event_test.rb +97 -0
- data/test/handlers/guards_test.rb +180 -0
- data/test/handlers/machine_test.rb +156 -0
- data/test/handlers/review_test.rb +192 -0
- data/test/handlers/state_test.rb +73 -0
- data/test/handlers/transition_test.rb +142 -0
- data/test/integration_test.rb +163 -0
- data/test/templates_test.rb +95 -0
- data/test/test_helper.rb +51 -0
- metadata +146 -16
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
require 'state_machines/yard/renderer'
|
|
5
|
+
|
|
6
|
+
# Code conditions, reopened and inherited machines, code-valued state
|
|
7
|
+
# options and numeric names, documented as the core reads them
|
|
8
|
+
class ReviewTest < Minitest::Test
|
|
9
|
+
include TestHelpers
|
|
10
|
+
|
|
11
|
+
def setup
|
|
12
|
+
setup_yard
|
|
13
|
+
@log = StringIO.new
|
|
14
|
+
@previous_log = [YARD::Logger.instance.io, YARD::Logger.instance.level]
|
|
15
|
+
YARD::Logger.instance.io = @log
|
|
16
|
+
YARD::Logger.instance.level = YARD::Logger::WARN # yardoc --quiet elsewhere raises it
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
def teardown
|
|
20
|
+
YARD::Logger.instance.io, YARD::Logger.instance.level = @previous_log
|
|
21
|
+
cleanup_yard
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
def test_a_code_condition_is_its_source_and_never_validated_as_a_string
|
|
25
|
+
machines = parse_machines(<<~RUBY)
|
|
26
|
+
class A
|
|
27
|
+
state_machine :status, initial: :a do
|
|
28
|
+
event(:go) { transition a: :b, if: -> { "system(" == "x" } }
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
RUBY
|
|
32
|
+
machine = machines['A'][:status]
|
|
33
|
+
|
|
34
|
+
assert_equal(:'-> { "system(" == "x" }', machine.events[:go].branches.first.if_condition)
|
|
35
|
+
assert_equal(['a -> b [if (-> { "system(" == "x" })]'],
|
|
36
|
+
StateMachines::Yard::Description.events(machine).first[:transitions])
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def test_a_string_condition_the_core_refuses_is_reported_not_raised
|
|
40
|
+
parse_code(<<~RUBY)
|
|
41
|
+
class A
|
|
42
|
+
state_machine :status, initial: :a do
|
|
43
|
+
event(:go) { transition a: :b, if: "system('ls')" }
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
RUBY
|
|
47
|
+
|
|
48
|
+
assert_includes(YARD::Registry.at('A#go').docstring, 'Its transitions cannot be described')
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def test_a_renderer_raising_a_security_error_leaves_the_diagram_out
|
|
52
|
+
machine = parse_machines(<<~RUBY)['A'][:status]
|
|
53
|
+
class A
|
|
54
|
+
state_machine :status, initial: :a do
|
|
55
|
+
event(:go) { transition a: :b, if: "system('ls')" }
|
|
56
|
+
end
|
|
57
|
+
end
|
|
58
|
+
RUBY
|
|
59
|
+
previous = ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
60
|
+
ENV['STATE_MACHINES_RENDERER'] = 'mermaid'
|
|
61
|
+
|
|
62
|
+
assert_nil(StateMachines::Yard::Renderer.render(machine))
|
|
63
|
+
ensure
|
|
64
|
+
ENV['STATE_MACHINES_RENDERER'] = previous
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def test_a_reopened_machine_is_extended
|
|
68
|
+
machines = parse_machines(<<~RUBY)
|
|
69
|
+
class B
|
|
70
|
+
state_machine(:status, initial: :a) { event(:go) { transition a: :b } }
|
|
71
|
+
state_machine(:status) { event(:stop) { transition b: :a } }
|
|
72
|
+
end
|
|
73
|
+
RUBY
|
|
74
|
+
|
|
75
|
+
assert_equal(%i[go stop], machines['B'][:status].events.map(&:name))
|
|
76
|
+
refute_includes(@log.string, 'NoMethodError')
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
def test_a_reopened_machine_takes_only_what_the_core_lets_it_change
|
|
80
|
+
machines = parse_machines(<<~RUBY)
|
|
81
|
+
class B
|
|
82
|
+
state_machine(:status, initial: :a) { event(:go) { transition a: :b } }
|
|
83
|
+
state_machine(:status, initial: :b)
|
|
84
|
+
state_machine(:status, attribute: :other) { event(:never) { transition b: :a } }
|
|
85
|
+
end
|
|
86
|
+
RUBY
|
|
87
|
+
machine = machines['B'][:status]
|
|
88
|
+
|
|
89
|
+
assert_equal([:b], machine.states.select(&:initial?).map(&:name))
|
|
90
|
+
assert_equal(%i[go], machine.events.map(&:name))
|
|
91
|
+
assert_includes(@log.string, 'state machine is not documented')
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
REOPENED_WITH_AN_UNDRAWABLE_STATE = <<~RUBY
|
|
95
|
+
class B
|
|
96
|
+
state_machine(:status, initial: :a) { event(:go) { transition a: :b } }
|
|
97
|
+
state_machine(:status) { event(:empty) { transition b: :"" } }
|
|
98
|
+
end
|
|
99
|
+
RUBY
|
|
100
|
+
|
|
101
|
+
def test_a_reopened_machine_that_cannot_be_drawn_again_publishes_no_earlier_diagram
|
|
102
|
+
%w[mermaid graphviz].each do |renderer|
|
|
103
|
+
entry = with_renderer(renderer) do
|
|
104
|
+
parse_code(REOPENED_WITH_AN_UNDRAWABLE_STATE)
|
|
105
|
+
YARD::Registry.at('B')['state_machines'][:status]
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
assert_equal(%w[go empty], entry[:events].map { it[:name] }, renderer)
|
|
109
|
+
next assert_empty(entry.slice(:mermaid, :image, :renderer), renderer) if renderer == 'mermaid'
|
|
110
|
+
|
|
111
|
+
# GraphViz draws a state named "" (blank label): its diagram is the extended machine's
|
|
112
|
+
assert_equal(:graphviz, entry[:renderer])
|
|
113
|
+
end
|
|
114
|
+
assert_includes(@log.string, 'the reopened status machine could not be drawn again')
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
def test_a_reopened_machine_is_drawn_again
|
|
118
|
+
entry = with_renderer('mermaid') do
|
|
119
|
+
parse_code(<<~RUBY)
|
|
120
|
+
class B
|
|
121
|
+
state_machine(:status, initial: :a) { event(:go) { transition a: :b } }
|
|
122
|
+
state_machine(:status) { event(:stop) { transition b: :a } }
|
|
123
|
+
end
|
|
124
|
+
RUBY
|
|
125
|
+
YARD::Registry.at('B')['state_machines'][:status]
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
assert_includes(entry[:mermaid], 'b --> a')
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
def test_a_subclass_machine_takes_its_own_options
|
|
132
|
+
machines = parse_machines(<<~RUBY)
|
|
133
|
+
class V
|
|
134
|
+
state_machine(:status, initial: :parked) { event(:go) { transition parked: :moving } }
|
|
135
|
+
end
|
|
136
|
+
class Car < V
|
|
137
|
+
state_machine(:status, initial: :moving)
|
|
138
|
+
end
|
|
139
|
+
RUBY
|
|
140
|
+
|
|
141
|
+
assert_equal([:moving], machines['Car'][:status].states.select(&:initial?).map(&:name))
|
|
142
|
+
assert_equal([:parked], machines['V'][:status].states.select(&:initial?).map(&:name))
|
|
143
|
+
end
|
|
144
|
+
|
|
145
|
+
def test_state_options_written_as_code_are_their_source
|
|
146
|
+
machine = parse_machines(<<~RUBY)['C'][:status]
|
|
147
|
+
class C
|
|
148
|
+
state_machine :status, initial: :idle do
|
|
149
|
+
state :idle, value: -> { 42 }, human_name: I18n.t('idle')
|
|
150
|
+
end
|
|
151
|
+
end
|
|
152
|
+
RUBY
|
|
153
|
+
idle = machine.states[:idle]
|
|
154
|
+
|
|
155
|
+
assert_equal('-> { 42 }', idle.value(false).inspect)
|
|
156
|
+
assert_equal("I18n.t('idle')", idle.human_name.to_s)
|
|
157
|
+
assert_includes(@log.string, 'value: is code (`-> { 42 }`), documented as its source')
|
|
158
|
+
end
|
|
159
|
+
|
|
160
|
+
def test_numeric_names_are_names
|
|
161
|
+
machine = parse_machines(<<~RUBY)['D'][:status]
|
|
162
|
+
class D
|
|
163
|
+
state_machine :status, initial: 1 do
|
|
164
|
+
state 1, 2.5
|
|
165
|
+
event(:go) { transition 1 => 2 }
|
|
166
|
+
end
|
|
167
|
+
end
|
|
168
|
+
RUBY
|
|
169
|
+
|
|
170
|
+
# 2.5 is refused by the core: every state name must be of one class
|
|
171
|
+
assert_equal([1, 2], machine.states.map(&:name))
|
|
172
|
+
assert_includes(@log.string, 'state is not documented: 2.5 state defined as Float')
|
|
173
|
+
assert_equal([1], machine.states.select(&:initial?).map(&:name))
|
|
174
|
+
assert_equal(1, machine.events[:go].branches.size)
|
|
175
|
+
end
|
|
176
|
+
|
|
177
|
+
def with_renderer(renderer)
|
|
178
|
+
previous = ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
179
|
+
ENV['STATE_MACHINES_RENDERER'] = renderer
|
|
180
|
+
YARD::Registry.clear
|
|
181
|
+
yield
|
|
182
|
+
ensure
|
|
183
|
+
ENV['STATE_MACHINES_RENDERER'] = previous
|
|
184
|
+
end
|
|
185
|
+
|
|
186
|
+
def test_generated_methods_document_their_parameters
|
|
187
|
+
parse_code('class E; state_machine(:status, initial: :a) { event(:go) { transition a: :b } }; end')
|
|
188
|
+
|
|
189
|
+
refute_includes(@log.string, 'unknown parameter name')
|
|
190
|
+
assert_equal([['state', nil]], YARD::Registry.at('E.human_status_name').parameters)
|
|
191
|
+
end
|
|
192
|
+
end
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
|
|
5
|
+
class StateHandlerTest < Minitest::Test
|
|
6
|
+
include TestHelpers
|
|
7
|
+
|
|
8
|
+
def setup
|
|
9
|
+
setup_yard
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
def teardown
|
|
13
|
+
cleanup_yard
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def test_state_handler_registers_states
|
|
17
|
+
code = <<-RUBY
|
|
18
|
+
class Vehicle
|
|
19
|
+
state_machine :status, initial: :parked do
|
|
20
|
+
# Parked state
|
|
21
|
+
state :parked do
|
|
22
|
+
# State behavior
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
# Moving state
|
|
26
|
+
state :moving
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
RUBY
|
|
30
|
+
|
|
31
|
+
parse_code(code)
|
|
32
|
+
|
|
33
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
34
|
+
|
|
35
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
36
|
+
|
|
37
|
+
# Check for methods that should be generated for states
|
|
38
|
+
parked_method = YARD::Registry.at('Vehicle#parked?')
|
|
39
|
+
|
|
40
|
+
refute_nil parked_method, 'parked? method should be registered'
|
|
41
|
+
assert_equal 'Checks whether :parked is the current state.', parked_method.docstring.to_s
|
|
42
|
+
|
|
43
|
+
moving_method = YARD::Registry.at('Vehicle#moving?')
|
|
44
|
+
|
|
45
|
+
refute_nil moving_method, 'moving? method should be registered'
|
|
46
|
+
assert_equal 'Checks whether :moving is the current state.', moving_method.docstring.to_s
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
def test_state_handler_with_multiple_states
|
|
50
|
+
code = <<-RUBY
|
|
51
|
+
class Vehicle
|
|
52
|
+
state_machine :status do
|
|
53
|
+
# These are the possible states
|
|
54
|
+
state :parked, :idling, :moving
|
|
55
|
+
end
|
|
56
|
+
end
|
|
57
|
+
RUBY
|
|
58
|
+
|
|
59
|
+
parse_code(code)
|
|
60
|
+
|
|
61
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
62
|
+
|
|
63
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
64
|
+
|
|
65
|
+
# Check for methods that should be generated for each state
|
|
66
|
+
%w[parked idling moving].each do |state|
|
|
67
|
+
method = YARD::Registry.at("Vehicle##{state}?")
|
|
68
|
+
|
|
69
|
+
refute_nil method, "#{state}? method should be registered"
|
|
70
|
+
assert_equal "Checks whether :#{state} is the current state.", method.docstring.to_s
|
|
71
|
+
end
|
|
72
|
+
end
|
|
73
|
+
end
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
|
|
5
|
+
class TransitionHandlerTest < Minitest::Test
|
|
6
|
+
include TestHelpers
|
|
7
|
+
|
|
8
|
+
def setup
|
|
9
|
+
setup_yard
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
def teardown
|
|
13
|
+
cleanup_yard
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def test_transition_handler_in_event_context
|
|
17
|
+
code = <<-RUBY
|
|
18
|
+
class Vehicle
|
|
19
|
+
state_machine :status, initial: :parked do
|
|
20
|
+
event :ignite do
|
|
21
|
+
# Transition from parked to idling
|
|
22
|
+
transition parked: :idling
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
RUBY
|
|
27
|
+
|
|
28
|
+
parse_code(code)
|
|
29
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
30
|
+
|
|
31
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
32
|
+
|
|
33
|
+
# Check for transitions documentation through the event methods
|
|
34
|
+
ignite_method = YARD::Registry.at('Vehicle#ignite')
|
|
35
|
+
|
|
36
|
+
refute_nil ignite_method, 'ignite method should be registered'
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def test_transition_handler_with_multiple_states
|
|
40
|
+
code = <<-RUBY
|
|
41
|
+
class Vehicle
|
|
42
|
+
state_machine :status, initial: :parked do
|
|
43
|
+
event :drive do
|
|
44
|
+
# Transition from multiple states
|
|
45
|
+
transition [:idling, :parked] => :moving
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
RUBY
|
|
50
|
+
|
|
51
|
+
parse_code(code)
|
|
52
|
+
|
|
53
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
54
|
+
|
|
55
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
56
|
+
|
|
57
|
+
# The drive method should be registered
|
|
58
|
+
drive_method = YARD::Registry.at('Vehicle#drive')
|
|
59
|
+
|
|
60
|
+
refute_nil drive_method, 'drive method should be registered'
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
def test_transition_handler_with_conditional
|
|
64
|
+
code = <<-RUBY
|
|
65
|
+
class Vehicle
|
|
66
|
+
state_machine :status, initial: :parked do
|
|
67
|
+
event :drive do
|
|
68
|
+
# Transition with a conditional
|
|
69
|
+
transition parked: :moving, if: :engine_started?
|
|
70
|
+
end
|
|
71
|
+
end
|
|
72
|
+
end
|
|
73
|
+
RUBY
|
|
74
|
+
|
|
75
|
+
parse_code(code)
|
|
76
|
+
|
|
77
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
78
|
+
|
|
79
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
80
|
+
|
|
81
|
+
# The drive method should be registered despite the conditional
|
|
82
|
+
drive_method = YARD::Registry.at('Vehicle#drive')
|
|
83
|
+
|
|
84
|
+
refute_nil drive_method, 'drive method should be registered'
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
def test_transition_handler_preserves_static_guards
|
|
88
|
+
code = <<-RUBY
|
|
89
|
+
class Vehicle
|
|
90
|
+
state_machine :gate, initial: :locked do
|
|
91
|
+
event :unlock do
|
|
92
|
+
transition locked: :unlocked
|
|
93
|
+
end
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
state_machine :status, initial: :parked do
|
|
97
|
+
event :drive do
|
|
98
|
+
transition parked: :moving, if: :engine_started?, if_state: { gate: :unlocked }
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
RUBY
|
|
103
|
+
|
|
104
|
+
branch = parse_machines(code)['Vehicle'][:status].events[:drive].branches.first
|
|
105
|
+
|
|
106
|
+
assert_equal :engine_started?, branch.if_condition
|
|
107
|
+
assert_equal({ if_state: { gate: :unlocked } }, branch.state_guards)
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
def test_transition_handler_with_special_matchers
|
|
111
|
+
code = <<-RUBY
|
|
112
|
+
class Vehicle
|
|
113
|
+
state_machine :status, initial: :parked do
|
|
114
|
+
event :repair do
|
|
115
|
+
# Use 'all' matcher
|
|
116
|
+
transition any => :parked
|
|
117
|
+
end
|
|
118
|
+
#{' '}
|
|
119
|
+
event :maintain do
|
|
120
|
+
# Use 'same' matcher
|
|
121
|
+
transition all => same
|
|
122
|
+
end
|
|
123
|
+
end
|
|
124
|
+
end
|
|
125
|
+
RUBY
|
|
126
|
+
|
|
127
|
+
parse_code(code)
|
|
128
|
+
|
|
129
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
130
|
+
|
|
131
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
132
|
+
|
|
133
|
+
# Both methods should be registered
|
|
134
|
+
repair_method = YARD::Registry.at('Vehicle#repair')
|
|
135
|
+
|
|
136
|
+
refute_nil repair_method, 'repair method should be registered'
|
|
137
|
+
|
|
138
|
+
maintain_method = YARD::Registry.at('Vehicle#maintain')
|
|
139
|
+
|
|
140
|
+
refute_nil maintain_method, 'maintain method should be registered'
|
|
141
|
+
end
|
|
142
|
+
end
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
|
|
5
|
+
class IntegrationTest < Minitest::Test
|
|
6
|
+
include TestHelpers
|
|
7
|
+
|
|
8
|
+
def setup
|
|
9
|
+
setup_yard
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
def teardown
|
|
13
|
+
cleanup_yard
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def test_full_documentation_integration
|
|
17
|
+
# Create a more complex class with state machine
|
|
18
|
+
code = <<-RUBY
|
|
19
|
+
# A vehicle class representing automobiles
|
|
20
|
+
# @author Test Author
|
|
21
|
+
class Vehicle
|
|
22
|
+
# The vehicle's engine state
|
|
23
|
+
# @return [Boolean] true if the engine is on, false otherwise
|
|
24
|
+
attr_accessor :engine_on
|
|
25
|
+
# Status state machine tracks the operational status of the vehicle
|
|
26
|
+
state_machine :status, initial: :parked do
|
|
27
|
+
description "Controls the vehicle's operational status"
|
|
28
|
+
#{' '}
|
|
29
|
+
# Parked state - vehicle is not moving and can be started
|
|
30
|
+
state :parked do
|
|
31
|
+
description "Vehicle is stopped and secured"
|
|
32
|
+
end
|
|
33
|
+
#{' '}
|
|
34
|
+
# Idling state - engine is running but vehicle is not moving
|
|
35
|
+
state :idling do
|
|
36
|
+
description "Engine is running but vehicle is stationary"
|
|
37
|
+
end
|
|
38
|
+
#{' '}
|
|
39
|
+
# Moving state - vehicle is in motion
|
|
40
|
+
state :moving do
|
|
41
|
+
description "Vehicle is in motion"
|
|
42
|
+
end
|
|
43
|
+
#{' '}
|
|
44
|
+
# Stalled state - vehicle has encountered a problem
|
|
45
|
+
state :stalled do
|
|
46
|
+
description "Vehicle has encountered a problem"
|
|
47
|
+
end
|
|
48
|
+
#{' '}
|
|
49
|
+
# Ignition event - turns on the engine
|
|
50
|
+
event :ignite do
|
|
51
|
+
description "Starts the vehicle's engine"
|
|
52
|
+
transition parked: :idling
|
|
53
|
+
end
|
|
54
|
+
#{' '}
|
|
55
|
+
# Drive event - puts vehicle in motion
|
|
56
|
+
event :drive do
|
|
57
|
+
description "Puts the vehicle in motion"
|
|
58
|
+
transition idling: :moving
|
|
59
|
+
end
|
|
60
|
+
#{' '}
|
|
61
|
+
# Stop event - brings vehicle to a stop
|
|
62
|
+
event :stop do
|
|
63
|
+
description "Stops the vehicle"
|
|
64
|
+
transition moving: :idling
|
|
65
|
+
end
|
|
66
|
+
#{' '}
|
|
67
|
+
# Park event - secure the vehicle
|
|
68
|
+
event :park do
|
|
69
|
+
description "Secures the vehicle"
|
|
70
|
+
transition idling: :parked
|
|
71
|
+
end
|
|
72
|
+
#{' '}
|
|
73
|
+
# Stall event - unexpected problem
|
|
74
|
+
event :stall do
|
|
75
|
+
description "Vehicle encountered a problem"
|
|
76
|
+
transition [:idling, :moving] => :stalled
|
|
77
|
+
end
|
|
78
|
+
#{' '}
|
|
79
|
+
# Repair event - fix the stalled vehicle
|
|
80
|
+
event :repair do
|
|
81
|
+
description "Fix vehicle issues"
|
|
82
|
+
transition stalled: :parked
|
|
83
|
+
end
|
|
84
|
+
end
|
|
85
|
+
#{' '}
|
|
86
|
+
# Second state machine for the gear position
|
|
87
|
+
state_machine :gear, initial: :neutral do
|
|
88
|
+
state :neutral
|
|
89
|
+
state :first
|
|
90
|
+
state :second
|
|
91
|
+
state :third
|
|
92
|
+
#{' '}
|
|
93
|
+
event :shift_up do
|
|
94
|
+
transition neutral: :first, first: :second, second: :third
|
|
95
|
+
end
|
|
96
|
+
#{' '}
|
|
97
|
+
event :shift_down do
|
|
98
|
+
transition third: :second, second: :first, first: :neutral
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
RUBY
|
|
103
|
+
|
|
104
|
+
parse_code(code)
|
|
105
|
+
|
|
106
|
+
# Verify YARD Registry
|
|
107
|
+
vehicle_class = YARD::Registry.at('Vehicle')
|
|
108
|
+
|
|
109
|
+
refute_nil vehicle_class, 'Vehicle class should be registered'
|
|
110
|
+
|
|
111
|
+
# Check state machines attribute exists
|
|
112
|
+
assert attribute?(vehicle_class, 'state_machines'), 'Vehicle class should have state_machines attribute'
|
|
113
|
+
assert_equal 2, vehicle_class['state_machines'].size, 'Vehicle should have two state machines'
|
|
114
|
+
|
|
115
|
+
# Check both state machines exist
|
|
116
|
+
assert vehicle_class['state_machines'].key?(:status), 'Vehicle should have a status state machine'
|
|
117
|
+
assert vehicle_class['state_machines'].key?(:gear), 'Vehicle should have a gear state machine'
|
|
118
|
+
|
|
119
|
+
# Check state methods
|
|
120
|
+
%w[parked? idling? moving? stalled? neutral? first? second? third?].each do |method_name|
|
|
121
|
+
method = YARD::Registry.at("Vehicle##{method_name}")
|
|
122
|
+
|
|
123
|
+
refute_nil method, "#{method_name} method should be registered"
|
|
124
|
+
end
|
|
125
|
+
|
|
126
|
+
# Check event methods for status machine
|
|
127
|
+
%w[ignite drive stop park stall repair].each do |event|
|
|
128
|
+
method = YARD::Registry.at("Vehicle##{event}")
|
|
129
|
+
|
|
130
|
+
refute_nil method, "#{event} method should be registered"
|
|
131
|
+
bang_method = YARD::Registry.at("Vehicle##{event}!")
|
|
132
|
+
|
|
133
|
+
refute_nil bang_method, "#{event}! method should be registered"
|
|
134
|
+
end
|
|
135
|
+
|
|
136
|
+
# Check event methods for gear machine
|
|
137
|
+
%w[shift_up shift_down].each do |event|
|
|
138
|
+
method = YARD::Registry.at("Vehicle##{event}")
|
|
139
|
+
|
|
140
|
+
refute_nil method, "#{event} method should be registered"
|
|
141
|
+
bang_method = YARD::Registry.at("Vehicle##{event}!")
|
|
142
|
+
|
|
143
|
+
refute_nil bang_method, "#{event}! method should be registered"
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
# Check attribute-related methods
|
|
147
|
+
status_method = YARD::Registry.at('Vehicle#status')
|
|
148
|
+
|
|
149
|
+
refute_nil status_method, 'status method should be registered'
|
|
150
|
+
|
|
151
|
+
status_events_method = YARD::Registry.at('Vehicle#status_events')
|
|
152
|
+
|
|
153
|
+
refute_nil status_events_method, 'status_events method should be registered'
|
|
154
|
+
|
|
155
|
+
# Generate documentation
|
|
156
|
+
YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
|
|
157
|
+
|
|
158
|
+
# Check if the HTML file was generated
|
|
159
|
+
html_file = File.join(@yard_dir, 'Vehicle.html')
|
|
160
|
+
|
|
161
|
+
assert_path_exists html_file, 'HTML file for Vehicle should exist'
|
|
162
|
+
end
|
|
163
|
+
end
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'test_helper'
|
|
4
|
+
require 'nokogiri'
|
|
5
|
+
|
|
6
|
+
class TemplatesTest < Minitest::Test
|
|
7
|
+
include TestHelpers
|
|
8
|
+
|
|
9
|
+
def setup
|
|
10
|
+
setup_yard
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
def teardown
|
|
14
|
+
cleanup_yard
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
def test_html_template_rendering
|
|
18
|
+
# Create a sample class with a state machine
|
|
19
|
+
code = <<-RUBY
|
|
20
|
+
# A vehicle class
|
|
21
|
+
# @author Test Author
|
|
22
|
+
class Vehicle
|
|
23
|
+
# This is a state machine for vehicle status
|
|
24
|
+
state_machine :status, initial: :parked do
|
|
25
|
+
state :parked
|
|
26
|
+
state :idling
|
|
27
|
+
state :moving
|
|
28
|
+
#{' '}
|
|
29
|
+
event :ignite do
|
|
30
|
+
transition parked: :idling
|
|
31
|
+
end
|
|
32
|
+
#{' '}
|
|
33
|
+
event :drive do
|
|
34
|
+
transition idling: :moving
|
|
35
|
+
end
|
|
36
|
+
#{' '}
|
|
37
|
+
event :park do
|
|
38
|
+
transition moving: :parked
|
|
39
|
+
end
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
RUBY
|
|
43
|
+
|
|
44
|
+
parse_code(code)
|
|
45
|
+
|
|
46
|
+
# Generate documentation
|
|
47
|
+
options = YARD::CLI::YardocOptions.new
|
|
48
|
+
options.files = []
|
|
49
|
+
options.output = @yard_dir
|
|
50
|
+
|
|
51
|
+
YARD::CLI::Yardoc.run('--no-save', '--no-progress', '--quiet', '-o', @yard_dir)
|
|
52
|
+
|
|
53
|
+
# Check if the HTML file was generated
|
|
54
|
+
html_file = File.join(@yard_dir, 'Vehicle.html')
|
|
55
|
+
|
|
56
|
+
assert_path_exists html_file, 'HTML file for Vehicle should exist'
|
|
57
|
+
|
|
58
|
+
# Parse the HTML and check for state machine content
|
|
59
|
+
html = File.read(html_file)
|
|
60
|
+
doc = Nokogiri::HTML(html)
|
|
61
|
+
|
|
62
|
+
# Check for state machine section
|
|
63
|
+
state_machines_section = doc.at_css('h2:contains("State Machines")')
|
|
64
|
+
|
|
65
|
+
refute_nil state_machines_section, 'State Machines section should exist in the HTML'
|
|
66
|
+
|
|
67
|
+
# Check for status machine
|
|
68
|
+
status_machine = doc.at_css('h3:contains("status")')
|
|
69
|
+
|
|
70
|
+
refute_nil status_machine, 'Status machine heading should exist in the HTML'
|
|
71
|
+
|
|
72
|
+
# Check for description
|
|
73
|
+
description = status_machine.next_element
|
|
74
|
+
|
|
75
|
+
refute_nil description, 'Machine description should exist'
|
|
76
|
+
assert_equal 'This is a state machine for vehicle status', description.text.strip
|
|
77
|
+
|
|
78
|
+
case ENV.fetch('STATE_MACHINES_RENDERER', nil)
|
|
79
|
+
when 'graphviz'
|
|
80
|
+
image = doc.at_css('img[alt^="State machine diagram for"]')
|
|
81
|
+
|
|
82
|
+
refute_nil image, 'Graphviz image should be rendered'
|
|
83
|
+
when 'mermaid'
|
|
84
|
+
mermaid_block = doc.at_css('pre.mermaid')
|
|
85
|
+
|
|
86
|
+
refute_nil mermaid_block, 'Mermaid block should be rendered'
|
|
87
|
+
else
|
|
88
|
+
image = doc.at_css('img[alt^="State machine diagram for"]')
|
|
89
|
+
mermaid_block = doc.at_css('pre.mermaid')
|
|
90
|
+
|
|
91
|
+
assert_nil image, 'No image should be rendered'
|
|
92
|
+
assert_nil mermaid_block, 'No mermaid block should be rendered'
|
|
93
|
+
end
|
|
94
|
+
end
|
|
95
|
+
end
|