base on AASM - State machines for Ruby classes (plain Ruby, ActiveRecord, Mongoid, NoBrainer, Dynamoid) # AASM - Ruby state machines [](http://badge.fury.io/rb/aasm) [](https://github.com/aasm/aasm/actions/workflows/build.yml) [](https://codeclimate.com/github/aasm/aasm) [](https://codecov.io/gh/aasm/aasm) ## Index - [Upgrade from version 3 to 4](#upgrade-from-version-3-to-4) - [Usage](#usage) - [Callbacks](#callbacks) - [Lifecycle](#lifecycle) - [The current event triggered](#the-current-event-triggered) - [Guards](#guards) - [Transitions](#transitions) - [Multiple state machines per class](#multiple-state-machines-per-class) - [Handling naming conflicts between multiple state machines](#handling-naming-conflicts-between-multiple-state-machines) - [Binding event](#binding-event) - [Auto-generated Status Constants](#auto-generated-status-constants) - [Extending AASM](#extending-aasm) - [ActiveRecord](#activerecord) - [Bang events](#bang-events) - [Timestamps](#timestamps) - [ActiveRecord enums](#activerecord-enums) - [Sequel](#sequel) - [Dynamoid](#dynamoid) - [Mongoid](#mongoid) - [Nobrainer](#nobrainer) - [Redis](#redis) - [Automatic Scopes](#automatic-scopes) - [Transaction support](#transaction-support) - [Pessimistic Locking](#pessimistic-locking) - [Column name & migration](#column-name--migration) - [Log State Changes](#log-state-changes) - [Inspection](#inspection) - [Warning output](#warning-output) - [RubyMotion support](#rubymotion-support) - [Testing](#testing) - [RSpec](#rspec) - [Minitest](#minitest) - [Assertions](#assertions) - [Expectations](#expectations) - [Installation](#installation) - [Manually from RubyGems.org](#manually-from-rubygemsorg) - [Bundler](#or-if-you-are-using-bundler) - [Building your own gems](#building-your-own-gems) - [Generators](#generators) - [Test suite with Docker](#docker) - [Latest changes](#latest-changes) - [Questions?](#questions) - [Maintainers](#maintainers) - [Contributing](CONTRIBUTING.md) - [Warranty](#warranty) - [License](#license) This package contains AASM, a library for adding finite state machines to Ruby classes. AASM started as the *acts_as_state_machine* plugin but has evolved into a more generic library that no longer targets only ActiveRecord models. It currently provides adapters for many ORMs but it can be used for any Ruby class, no matter what parent class it has (if any). ## Upgrade from version 3 to 4 Take a look at the [README_FROM_VERSION_3_TO_4](https://github.com/aasm/aasm/blob/master/README_FROM_VERSION_3_TO_4.md) for details how to switch from version 3.x to 4.0 of _AASM_. ## Usage Adding a state machine is as simple as including the AASM module and start defining **states** and **events** together with their **transitions**: ```ruby class Job include AASM aasm do state :sleeping, initial: true state :running, :cleaning event :run do transitions from: :sleeping, to: :running end event :clean do transitions from: :running, to: :cleaning end event :sleep do transitions from: [:running, :cleaning], to: :sleeping end end end ``` This provides you with a couple of public methods for instances of the class `Job`: ```ruby job = Job.new job.sleeping? # => true job.may_run? # => true job.run job.running? # => true job.sleeping? # => false job.may_run? # => false job.run # => raises AASM::InvalidTransition ``` If you don't like exceptions and prefer a simple `true` or `false` as response, tell AASM not to be *whiny*: ```ruby class Job ... aasm whiny_transitions: false do ... end end job.running? # => true job.may_run? # => false job.run # => false ``` When firing an event, you can pass a block to the method, it will be called only if the transition succeeds : ```ruby job.run do job.user.notify_job_ran # Will be called if job.may_run? is true end ``` ### Callbacks You can define a number of callbacks for your events, transitions and states. These methods, Procs or classes will be called when certain criteria are met, like entering a particular state: ```ruby class Job include AASM aasm do state :sleeping, initial: true, before_enter: :do_something state :running, before_enter: Proc.new { do_something && notify_somebody } state :finished after_all_transitions :log_status_change event :run, after: :notify_somebody do before do log('Preparing to run') end transitions from: :sleeping, to: :running, after: Proc.new {|*args| set_process(*args) } transitions from: :running, to: :finished, after: LogRunTime end event :sleep do after do ... end error do |e| ... end transitions from: :running, to: :sleeping end end def log_status_change puts "changing from #{aasm.from_state} to #{aasm.to_state} (event: #{aasm.current_event})" end def set_process(name) ... end def do_something ... end def notify_somebody ... end end class LogRunTime def call log "Job was running for X seconds" end end ``` In this case `do_something` is called before actually entering the state `sleeping`, while `notify_somebody` is called after the transition `run` (from `sleeping` to `running`) is finished. AASM will also initialize `LogRunTime` and run the `call` method for you after the transition from `running` to `finished` in the example above. You can pass arguments to the class by defining an initialize method on it, like this: Note that Procs are executed in the context of a record, it means that you don't need to expect the record as an argument, just call the methods you need. ```ruby class LogRunTime # optional args parameter can be omitted, but if you define initialize # you must accept the model instance as the first parameter to it. def initialize(job, args = {}) @job = job end def call log "Job was running for #{@job.run_time} seconds" end end ``` #### Parameters You can pass parameters to events: ```ruby job = Job.new job.run(:defragmentation) ``` All guards and after callbacks will receive these parameters. In this case `set_process` would be called with `:defragmentation` argument. If the first argument to the event is a state (e.g. `:running` or `:finished`), the first argument is consumed and the state machine will attempt to transition to that state. Add comma separated parameter for guards and callbacks ```ruby job = Job.new job.run(:running, :defragmentation) ``` In this case `set_process` won't be called, job will transition to running state and callback will receive `:defragmentation` as parameter #### Error Handling In case of an error during the event processing the error is rescued and passed to `:error` callback, which can handle it or re-raise it for further propagation. Also, you can define a method that will be called if any event fails: ```ruby def aasm_event_failed(event_name, old_state_name) # use custom exception/messages, report metrics, etc end ``` During the transition's `:after` callback (and reliably only then, or in the global `after_all_transitions` callback) you can access the originating state (the from-state) and the target state (the to state), like this: ```ruby def set_process(name) logger.info "from #{aasm.from_state} to #{aasm.to_state}" end ``` #### Lifecycle Here you can see a list of all possible callbacks, together with their order of calling: ```ruby begin event before_all_events event before event guards transition guards old_state before_exit old_state exit after_all_transitions transition after new_state before_enter new_state enter ...update state... event before_success # if persist successful transition success # if persist successful, database update not guaranteed event success # if persist successful, database update not guaranteed old_state after_exit new_state after_enter event after event after_all_events rescue event error event error_on_all_events ensure event ensure event ensure_on_all_events end ``` Use event's `after_commit` callback if it should be fired after database update. #### The current event triggered While running the callbacks you can easily retrieve the name of the event triggered by using `aasm.current_event`: ```ruby # taken the example callback from above def do_something puts "triggered #{aasm.current_event}" end ``` and then ```ruby job = Job.new # without bang job.sleep # => triggered :sleep # with bang job.sleep! # => triggered :sleep! ``` ### Guards Let's assume you want to allow particular transitions only if a defined condition is given. For this you can set up a guard per transition, which will run before actually running the transition. If the guard returns `false` the transition will be denied (raising `AASM::InvalidTransition`): ```ruby class Cleaner include AASM aasm do state :idle, initial: true state :cleaning event :clean do transitions from: :idle, to: :cleaning, guard: :cleaning_needed? end event :clean_if_needed do transitions from: :idle, to: :cleaning do guard do cleaning_needed? end end transitions from: :idle, to: :idle end event :clean_if_dirty do transitions from: :idle, to: :cleaning, guard: :if_dirty? end end def cleaning_needed? false end def if_dirty?(status) status == :dirty end end job = Cleaner.new job.may_clean? # => false job.clean # => raises AASM::InvalidTransition job.may_clean_if_needed? # => true job.clean_if_needed! # idle job.clean_if_dirty(:clean) # => raises AASM::InvalidTransition job.clean_if_dirty(:dirty) # => true ``` You can even provide a number of guards, which all have to succeed to proceed ```ruby def walked_the_dog?; ...; end event :sleep do transitions from: :running, to: :sleeping, guards: [:cleaning_needed?, :walked_the_dog?] end ``` If you want to provide guards for all transitions within an event, you can use event guards ```ruby event :sleep, guards: [:walked_the_dog?] do transitions from: :running, to: :sleeping, guards: [:cleaning_needed?] transitions from: :cleaning, to: :sleeping end ``` If you prefer a more Ruby-like guard syntax, you can use `if` and `unless` as well: ```ruby event :clean do transitions from: :running, to: :cleaning, if: :cleaning_needed? end event :sleep do transitions from: :running, to: :sleeping, unless: :cleaning_needed? end end ``` You can invoke a Class instead of a method if the Class responds to `call` ```ruby event :sleep do transitions from: :running, to: :sleeping, guards: Dog end ``` ```ruby class Dog def call cleaning_needed? && walked? end ... end ``` ### Transitions In the event of having multiple transitions for an event, the first transition that successfully completes will stop other transitions in the same event from being processed. ```ruby require 'aasm' class Job include AASM aasm do state :stage1, initial: true state :stage2 state :stage3 state :completed event :stage1_completed do transitions from: :stage1, to: :stage3, guard: :stage2_completed? transitions from: :stage1, to: :stage2 end end def stage2_completed? true end end job = Job.new job.stage1_completed job.aasm.current_state # stage3 ``` You can define transition from any defined state by omitting `from`: ```ruby event :abort do transitions to: :aborted end ``` ### Display name for state You can define display name for state using :display option ```ruby class Job include AASM aasm do state :stage1, initial: true, display: 'First Stage' state :stage2 state :stage3 end end job = Job.new job.aasm.human_state ``` ### Multiple state machines per class Multiple state machines per class are supported. Be aware though that _AASM_ has been built with one state machine per class in mind. Nonetheless, here's how to do it (see below). Please note that you will need to specify database columns for where your pertinent states will be stored - we have specified two columns `move_state` and `work_state` in the example below. See the [Column name & migration](https://github.com/aasm/aasm#column-name--migration) section for further info. ```ruby class SimpleMultipleExample include AASM aasm(:move, column: 'move_state') do state :standing, initial: true state :walking state :running event :walk do transitions from: :standing, to: :walking end event :run do transitions from: [:standing, :walking], to: :running end event :hold do transitions from: [:walking, :running], to: :standing end end aasm(:work, column: 'work_state') do state :sleeping, initial: true state :processing event :start do transitions from: :sleeping, to: :processing end event :stop do transitions from: :processing, to: :sleeping end end end simple = SimpleMultipleExample.new simple.aasm(:move).current_state # => :standing simple.aasm(:work).current_state # => :sleeping simple.start simple.aasm(:move).current_state # => :standing simple.aasm(:work).current_state # => :processing ``` #### Handling naming conflicts between multiple state machines _AASM_ doesn't prohibit to define the same event in more than one state machine. If no namespace is provided, the latest definition "wins" and overrides previous definitions. Nonetheless, a warning is issued: `SimpleMultipleExample: overriding method 'run'!`. Alternatively, you can provide a namespace for each state machine: ```ruby class NamespacedMultipleExample include AASM aasm(:status) do state :unapproved, initial: true state :approved event :approve do transitions from: :unapproved, to: :approved end event :unapprove do transitions from: :approved, to: :unapproved end end aasm(:review_status, namespace: :review) do state :unapproved, initial: true state :approved event :approve do transitions from: :unapproved, to: :approved end event :unapprove do transitions from: :approved, to: :unapproved end end end namespaced = NamespacedMultipleExample.new namespaced.aasm(:status).current_state # => :unapproved namespaced.aasm(:review_status).current_state # => :unapproved namespaced.approve_review namespaced.aasm(:review_status).current_state # => :approved ``` All _AASM_ class- and instance-level `aasm` methods accept a state machine selector. So, for example, to use inspection on a class level, you have to use ```ruby SimpleMultipleExample.aasm(:move).states.map(&:name) # => [:standing, :walking, :running] ``` ### Binding event Allow an event to be bound to another ```ruby class Example include AASM aasm(:work) do state :sleeping, initial: true state :processing event :start do transitions from: :sleeping, to: :processing end event :stop do transitions from: :processing, to: :sleeping end end aasm(:question) do state :answered, initial: true state :asked event :ask, binding_event: :start do transitions from: :answered, to: :asked end event :answer, binding_event: :stop do transitions from: :asked, to: :answered end end end example = Example.new example.aasm(:work).current_state #=> :sleeping example.aasm(:question).current_state #=> :answered example.ask example.aasm(:work).current_state #=> :processing example.aasm(:question).current_state #=> :asked ``` ### Auto-generated Status Constants AASM automatically [generates constants](https://github.com/aasm/aasm/pull/60) for each status so you don't have to explicitly define them. ```ruby class Foo include AASM aasm do state :initialized state :calculated state :finalized end end > Foo::STATE_INITIALIZED #=> :initialized > Foo::STATE_CALCULATED #=> :calculated ``` ### Extending AASM AASM allows you to easily extend `AASM::Base` for your own application purposes. Let's suppose we have common logic across many AASM models. We can embody this logic in a sub-class of `AASM::Base`. ```ruby class CustomAASMBase < AASM::Base # A custom transition that we want available across many AASM models. def count_transitions! klass.class_eval do aasm with_klass: CustomAASMBase do after_all_transitions :increment_transition_count end end end # A custom annotation that we want available across many AASM models. def requires_guards! klass.class_eval do attr_reader :authorizable_called, :transition_count, :fillable_called def authorizable? @authorizable_called = true end def fillable? @fillable_called = true end def increment_transition_count @transition_count ||= 0 @transition_count += 1 end end end end ``` When we declare our model that has an AASM state machine, we simply declare the AASM block with a `:with_klass` key to our own class. ```ruby class SimpleCustomExample include AASM # Let's build an AASM state machine with our custom class. aasm with_klass: CustomAASMBase do requires_guards! count_transitions! state :initialised, initial: true state :filled_out state :authorised event :fill_out do transitions from: :initialised, to: :filled_out, guard: :fillable? end event :authorise do transitions from: :filled_out, to: :authorised, guard: :authorizable? end end end ``` ### ActiveRecord AASM comes with support for ActiveRecord and allows automatic persisting of the object's state in the database. Add `gem 'after_commit_everywhere', '~> 1.0'` to your Gemfile. ```ruby class Job < ActiveRecord::Base include AASM aasm do # default column: aasm_state state :sleeping, initial: true state :running event :run do transitions from: :sleeping, to: :running end event :sleep do transitions from: :running, to: :sleeping end end end ``` ### Bang events You can tell AASM to auto-save the object or leave it unsaved ```ruby job = Job.new job.run # not saved job.run! # saved # or job.aasm.fire(:run) # not saved job.aasm.fire!(:run) # saved ``` Saving includes running all validations on the `Job` class. If `whiny_persistence` flag is set to `true`, exception is raised in case of failure. If `whiny_persistence` flag is set to `false`, methods with a bang return `true` if the state transition is successful or `false` if an error occurs. If you want make sure the state gets saved without running validations (and thereby maybe persisting an invalid object state), simply tell AASM to skip the validations. Be aware that when skipping validations, only the state column will be updated in the database (just like ActiveRecord `update_column` is working). ```ruby class Job < ActiveRecord::Base include AASM aasm skip_validation_on_save: true do state :sleeping, initial: true state :running event :run do transitions from: :sleeping, to: :running end event :sleep do transitions from: :running, to: :sleeping end end end ``` Also, you can skip the validation at instance level with `some_event_name_without_validation!` method. With this you have the flexibility of having validation for all your transitions by default and then skip it wherever required. Please note that only state column will be updated as mentioned in the above example. ```ruby job.run_without_validation! ``` If you want to make sure that the _AASM_ column for storing the state is not directly assigned, configure _AASM_ to not allow direct assignment, like this: ```ruby class Job < ActiveRecord::Base include AASM aasm no_direct_assignment: true do state :sleeping, initial: true state :running event :run do transitions from: :sleeping, to: :running end end end ``` resulting in this: ```ruby job = Job.create job.aasm_state # => 'sleeping' job.aasm_state = :running # => raises AASM::NoDirectAssignmentError job.aasm_state # => 'sleeping' ``` ### Timestamps You can tell _AASM_ to try to write a timestamp whenever a new state is entered. If `timestamps: true` is set, _AASM_ will look for a field named like the new state plus `_at` and try to fill it: ```ruby class Job < ActiveRecord::Base include AASM aasm timestamps: true do state :sleeping, initial: true state :running event :run do transitions from: :sleeping, to: :running end end end ``` resulting in this: ```ruby job = Job.create job.running_at # => nil job.run! job.running_at # => 2020-02-20 20:00:00 ``` Missing timestamp fields are silently ignored, so it is not necessary to have setters (such as ActiveRecord columns) for *all* states when using this option. #### ActiveRecord enums You can use [enumerations](http://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) in Rails 4.1+ for your state column: ```ruby class Job < ActiveRecord::Base include AASM enum state: { sleeping: 5, running: 99 } aasm column: :state, enum: true do state :sleeping, initial: true state :running end end ``` You can explicitly pass the name of the method which provides access to the enumeration mapping as a value of ```enum```, or you can simply set it to ```true```. In the latter case AASM will try to use pluralized column name to access possible enum states. Furthermore, if your column has integer type (which is normally the case when you're working with Rails enums), you can omit ```:enum``` setting --- AASM auto-detects this situation and enabled enum support. If anything goes wrong, you can disable enum functionality and fall back to the default behavior by setting ```:enum``` to ```false```. ### Sequel AASM also supports [Sequel](http://sequel.jeremyevans.net/) besides _ActiveRecord_, and _Mongoid_. ```ruby class Job < Sequel::Model include AASM aasm do # default column: aasm_state ... end end ``` However it's not yet as feature complete as _ActiveRecord_. For example, there are scopes defined yet. See [Automatic Scopes](#automatic-scopes). ### Dynamoid Since version `4.8.0` _AASM_ also supports [Dynamoid](http://joshsymonds.com/Dynamoid/) as persistence ORM. ### Mongoid AASM also supports persistence to Mongodb if you're using Mongoid. Make sure to include Mongoid::Document before you include AASM. ```ruby class Job include Mongoid::Document include AASM field :aasm_state aasm do ... end end ``` ### NoBrainer AASM also supports persistence to [RethinkDB](https://www.rethinkdb.com/) if you're using [Nobrainer](http://nobrainer.io/). Make sure to include NoBrainer::Document before you include AASM. ```ruby class Job include NoBrainer::Document include AASM field :aasm_state aasm do ... end end ``` ### Redis AASM also supports persistence in Redis via [Redis::Objects](https://github.com/nateware/redis-objects). Make sure to include Redis::Objects before you include AASM. Note that non-bang events will work as bang events, persisting the changes on every call. ```ruby class User include Redis::Objects include AASM aasm do end end ``` ### Automatic Scopes AASM will automatically create scope methods for each state in the model. ```ruby class Job < ActiveRecord::Base include AASM aasm do state :sleeping, initial: true state :running state :cleaning end def self.sleeping "This method name is already in use" end end ``` ```ruby class JobsController < ApplicationController def index @running_jobs = Job.running @recent_cleaning_jobs = Job.cleaning.where('created_at >= ?', 3.days.ago) # @sleeping_jobs = Job.sleeping #=> "This method name is already in use" end end ``` If you don't need scopes (or simply don't want them), disable their creation when defining the `AASM` states, like this: ```ruby class Job < ActiveRecord::Base include AASM aasm create_scopes: false do state :sleeping, initial: true state :running state :cleaning end end ``` ### Transaction support Since version *3.0.13* AASM supports ActiveRecord transactions. So whenever a transition callback or the state update fails, all changes to any database record are rolled back. Mongodb does not support transactions. There are currently 3 transactional callbacks that can be handled on the event, and 2 transactional callbacks for all events. ```ruby event before_all_transactions event before_transaction event aasm_fire_event (within transaction) event after_commit (if event successful) event after_transaction event after_all_transactions ``` If you want to make sure a depending action happens only after the transaction is committed, use the `after_commit` callback along with the auto-save (bang) methods, like this: ```ruby class Job < ActiveRecord::Base include AASM aasm do state :sleeping, initial: true state :running event :run, after_commit: :notify_about_running_job do transitions from: :sleeping, to: :running end end def notify_about_running_job ... end end job = Job.where(state: 'sleeping').first! job.run! # Saves the model and triggers the after_commit callback ``` Note that the following will not run the `after_commit` callbacks because the auto-save method is not used: ```ruby job = Job.where(state: 'sleeping').first! job.run job.save! #notify_about_running_job is not run ``` Please note that `:after_commit` AASM callbacks behaves around custom implementation of transaction pattern rather than a real-life DB transaction. This fact still causes the race conditions and redundant callback calls within nested transaction. In order to fix that it's highly recommended to add `gem 'after_commit_everywhere', '~> 1.0'` to your `Gemfile`. If you want to encapsulate state changes within an own transaction, the behavior of this nested transaction might be confusing. Take a look at [ActiveRecord Nested Transactions](http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html) if you want to know more about this. Nevertheless, AASM by default requires a new transaction `transaction(requires_new: true)`. You can override this behavior by changing the configuration ```ruby class Job < ActiveRecord::Base include AASM aasm requires_new_transaction: false do ... end ... end ``` which then leads to `transaction(requires_new: false)`, the Rails default. Additionally, if you do not want any of your ActiveRecord actions to be wrapped in a transaction, you can specify the `use_transactions` flag. This can be useful if you want want to persist things to the database that happen as a result of a transaction or callback, even when some error occurs. The `use_transactions` flag is true by default. ```ruby class Job < ActiveRecord::Base include AASM aasm use_transactions: false do ... end ... end ``` ### Pessimistic Locking AASM supports [ActiveRecord pessimistic locking via `with_lock`](http://api.rubyonrails.org/classes/ActiveRecord/Locking/Pessimistic.html#method-i-with_lock) for database persistence layers. | Option | Purpose | | ------ | ------- | | `false` (default) | No lock is obtained | | | `true` | Obtain a blocking pessimistic lock e.g. `FOR UPDATE` | | String | Obtain a lock based on the SQL string e.g. `FOR UPDATE NOWAIT` | ```ruby class Job < ActiveRecord::Base include AASM aasm requires_lock: true do ... end ... end ``` ```ruby class Job < ActiveRecord::Base include AASM aasm requires_lock: 'FOR UPDATE NOWAIT' do ... end ... end ``` ### Column name & migration As a default AASM uses the column `aasm_state` to store the states. You can override this by defining your favorite column name, using `:column` like this: ```ruby class Job < ActiveRecord::Base include AASM aasm column: :my_state do ... end aasm :another_state_machine, column: :second_state do ... end end ``` Whatever column name is used, make sure to add a migration to provide this column (of type `string`). Do not add default value for column at the database level. If you add default value in database then AASM callbacks on the initial state will not be fired upon instantiation of the model. ```ruby class AddJobState < ActiveRecord::Migration def self.up add_column :jobs, :aasm_state, :string end def self.down remove_column :jobs, :aasm_state end end ``` ### Log State Changes Logging state change can be done using [paper_trail](https://github.com/paper-trail-gem/paper_trail) gem Example of implementation can be found here [https://github.com/nitsujri/aasm-papertrail-example](https://github.com/nitsujri/aasm-papertrail-example) ### Inspection AASM supports query methods for states and events Given the following `Job` class: ```ruby class Job include AASM aasm do state :sleeping, initial: true state :running, :cleaning event :run do transitions from: :sleeping, to: :running end event :clean do transitions from: :running, to: :cleaning, guard: :cleaning_needed? end event :sleep do transitions from: [:running, :cleaning], to: :sleeping end end def cleaning_needed? false end end ``` ```ruby # show all states Job.aasm.states.map(&:name) #=> [:sleeping, :running, :cleaning] job = Job.new # show all permitted states (from initial state) job.aasm.states(permitted: true).map(&:name) #=> [:running] # List all the permitted transitions(event and state pairs) from initial state job.aasm.permitted_transitions #=> [{ :event => :run, :state => :running }] job.run job.aasm.states(permitted: true).map(&:name) #=> [:sleeping] # show all non permitted states job.aasm.states(permitted: false).map(&:name) #=> [:cleaning] # show all possible (triggerable) events from the current state job.aasm.events.map(&:name) #=> [:clean, :sleep] # show all permitted events job.aasm.events(permitted: true).map(&:name) #=> [:sleep] # show all non permitted events job.aasm.events(permitted: false).map(&:name) #=> [:clean] # show all possible events except a specific one job.aasm.events(reject: :sleep).map(&:name) #=> [:clean] # list states for select Job.aasm.states_for_select #=> [["Sleeping", "sleeping"], ["Running", "running"], ["Cleaning", "cleaning"]] # show permitted states with guard parameter job.aasm.states({permitted: true}, guard_parameter).map(&:name) ``` ### Warning output Warnings are by default printed to `STDERR`. If you want to log those warnings to another output, use ```ruby class Job include AASM aasm logger: Rails.logger do ... end end ``` You can hide warnings by setting `AASM::Configuration.hide_warnings = true` ### RubyMotion support Now supports [CodeDataQuery](https://github.com/infinitered/cdq.git) ! However I'm still in the process of submitting my compatibility updates to their repository. In the meantime you can use [my fork](https://github.com/Infotaku/cdq.git), there may still be some minor issues but I intend to extensively use it myself, so fixes should come fast. Warnings: - Due to RubyMotion Proc's lack of 'source_location' method, it may be harder to find out the origin of a "cannot transition from" error. I would recommend using the 'instance method symbol / string' way whenever possible when defining guardians and callbacks. ### Testing #### RSpec AASM provides some matchers for [RSpec](http://rspec.info): * `transition_from`, * `have_state`, `allow_event` * and `allow_transition_to`. ##### Installation Instructions: * Add `require 'aasm/rspec'` to your `spec_helper.rb` file. ##### Examples Of Usage in Rspec: ```ruby # classes with only the default state machine job = Job.new expect(job).to transition_from(:sleeping).to(:running).on_event(:run) expect(job).not_to transition_from(:sleeping).to(:cleaning).on_event(:run) expect(job).to have_state(:sleeping) expect(job).not_to have_state(:running) expect(job).to allow_event :run expect(job).to_not allow_event :clean expect(job).to allow_transition_to(:running) expect(job).to_not allow_transition_to(:cleaning) # on_event also accept multiple arguments expect(job).to transition_from(:sleeping).to(:running).on_event(:run, :defragmentation) # classes with multiple state machine multiple = SimpleMultipleExample.new expect(multiple).to transition_from(:standing).to(:walking).on_event(:walk).on(:move) expect(multiple).to_not transition_from(:standing).to(:running).on_event(:walk).on(:move) expect(multiple).to have_state(:standing).on(:move) expect(multiple).not_to have_state(:walking).on(:move) expect(multiple).to allow_event(:walk).on(:move) expect(multiple).to_not allow_event(:hold).on(:move) expect(multiple).to allow_transition_to(:walking).on(:move) expect(multiple).to_not allow_transition_to(:running).on(:move) expect(multiple).to transition_from(:sleeping).to(:processing).on_event(:start).on(:work) expect(multiple).to_not transition_from(:sleeping).to(:sleeping).on_event(:start).on(:work) expect(multiple).to have_state(:sleeping).on(:work) expect(multiple).not_to have_state(:processing).on(:work) expect(multiple).to allow_event(:start).on(:move) expect(multiple).to_not allow_event(:stop).on(:move) expect(multiple).to allow_transition_to(:processing).on(:move) expect(multiple).to_not allow_transition_to(:sleeping).on(:move) # allow_event also accepts arguments expect(job).to allow_event(:run).with(:defragmentation) ``` #### Minitest AASM provides assertions and rspec-like expectations for [Minitest](https://github.com/seattlerb/minitest). ##### Assertions List of supported assertions: `assert_have_state`, `refute_have_state`, `assert_transitions_from`, `refute_transitions_from`, `assert_event_allowed`, `refute_event_allowed`, `assert_transition_to_allowed`, `refute_transition_to_allowed`. ##### Examples Of Usage (Minitest): Add `require 'aasm/minitest'` to your `test_helper.rb` file and use them like this: ```ruby # classes with only the default state machine job = Job.new assert_transitions_from job, :sleeping, to: :running, on_event: :run refute_transitions_from job, :sleeping, to: :cleaning, on_event: :run assert_have_state job, :sleeping refute_have_state job, :running assert_event_allowed job, :run refute_event_allowed job, :clean assert_transition_to_allowed job, :running refute_transition_to_allowed job, :cleaning # on_event also accept arguments assert_transitions_from job, :sleeping, :defragmentation, to: :running, on_event: :run # classes with multiple state machine multiple = SimpleMultipleExample.new assert_transitions_from multiple, :standing, to: :walking, on_event: :walk, on: :move refute_transitions_from multiple, :standing, to: :running, on_event: :walk, on: :move assert_have_state multiple, :standing, on: :move refute_have_state multiple, :walking, on: :move assert_event_allowed multiple, :walk, on: :move refute_event_allowed multiple, :hold, on: :move assert_transition_to_allowed multiple, :walking, on: :move refute_transition_to_allowed multiple, :running, on: :move assert_transitions_from multiple, :sleeping, to: :processing, on_event: :start, on: :work refute_transitions_from multiple, :sleeping, to: :sleeping, on_event: :start, on: :work assert_have_state multiple, :sleeping, on: :work refute_have_state multiple, :processing, on: :work assert_event_allowed multiple, :start, on: :move refute_event_allowed multiple, :stop, on: :move assert_transition_to_allowed multiple, :processing, on: :move refute_transition_to_allowed multiple, :sleeping, on: :move ``` ##### Expectations List of supported expectations: `must_transition_from`, `wont_transition_from`, `must_have_state`, `wont_have_state`, `must_allow_event`, `wont_allow_event`, `must_allow_transition_to`, `wont_allow_transition_to`. Add `require 'aasm/minitest_spec'` to your `test_helper.rb` file and use them like this: ```ruby # classes with only the default state machine job = Job.new job.must_transition_from :sleeping, to: :running, on_event: :run job.wont_transition_from :sleeping, to: :cleaning, on_event: :run job.must_have_state :sleeping job.wont_have_state :running job.must_allow_event :run job.wont_allow_event :clean job.must_allow_transition_to :running job.wont_allow_transition_to :cleaning # on_event also accept arguments job.must_transition_from :sleeping, :defragmentation, to: :running, on_event: :run # classes with multiple state machine multiple = SimpleMultipleExample.new multiple.must_transition_from :standing, to: :walking, on_event: :walk, on: :move multiple.wont_transition_from :standing, to: :running, on_event: :walk, on: :move multiple.must_have_state :standing, on: :move multiple.wont_have_state :walking, on: :move multiple.must_allow_event :walk, on: :move multiple.wont_allow_event :hold, on: :move multiple.must_allow_transition_to :walking, on: :move multiple.wont_allow_transition_to :running, on: :move multiple.must_transition_from :sleeping, to: :processing, on_event: :start, on: :work multiple.wont_transition_from :sleeping, to: :sleeping, on_event: :start, on: :work multiple.must_have_state :sleeping, on: :work multiple.wont_have_state :processing, on: :work multiple.must_allow_event :start, on: :move multiple.wont_allow_event :stop, on: :move multiple.must_allow_transition_to :processing, on: :move multiple.wont_allow_transition_to :sleeping, on: :move ``` ## <a id="installation">Installation ## ### Manually from RubyGems.org ### ```sh % gem install aasm ``` ### Or if you are using Bundler ### ```ruby # Gemfile gem 'aasm' ``` ### Building your own gems ### ```sh % rake build % sudo gem install pkg/aasm-x.y.z.gem ``` ### Generators After installing AASM you can run generator: ```sh % rails generate aasm NAME [COLUMN_NAME] ``` Replace NAME with the Model name, COLUMN_NAME is optional(default is 'aasm_state'). This will create a model (if one does not exist) and configure it with aasm block. For ActiveRecord orm a migration file is added to add aasm state column to table. ### Docker Run test suite easily on docker ``` 1. docker-compose build aasm 2. docker-compose run --rm aasm ``` ## Latest changes ## Take a look at the [CHANGELOG](https://github.com/aasm/aasm/blob/master/CHANGELOG.md) for details about recent changes to the current version. ## Questions? ## Feel free to * [create an issue on GitHub](https://github.com/aasm/aasm/issues) * [ask a question on StackOverflow](http://stackoverflow.com) (tag with `aasm`) * send us a tweet [@aasm](http://twitter.com/aasm) ## Maintainers ## * [Scott Barron](https://github.com/rubyist) (2006–2009, original author) * [Travis Tilley](https://github.com/ttilley) (2009–2011) * [Thorsten Böttger](http://github.com/alto) (since 2011) * [Anil Maurya](http://github.com/anilmaurya) (since 2016) ## Stargazers over time [](https://starchart.cc/aasm/aasm) ## [Contributing](CONTRIBUTING.md) ## Warranty ## This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose. ## License ## Copyright (c) 2006-2017 Scott Barron 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. ", Assign "at most 3 tags" to the expected json: {"id":"5504","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"