Gema AASM: máquina de estados en Ruby on Rails
AASM es una gema de Ruby que convierte una clase, o un modelo de Rails, en una máquina de estados: tú dices qué estados existen y qué eventos pasan de uno a otro, y la gema impide cualquier paso que no hayas permitido.
Un artículo de un blog puede estar en borrador o publicado. Un pedido, pendiente, pagado o enviado. Si controlas esos cambios con if repartidos por el código, tarde o temprano alguien publica algo que ya estaba publicado o envía un pedido sin pagar.
Una máquina de estados pone orden: dice en qué estados puede estar algo y qué pasos llevan de uno a otro. Es como un semáforo: puede estar en verde, ámbar o rojo, y no salta de verde a rojo sin pasar por ámbar.
Las piezas de una máquina de estados
| Pieza | Qué es | En el ejemplo |
|---|---|---|
| Estado | Situación en la que está el objeto | in_draft (borrador) y published (publicado) |
| Estado inicial | El que tiene al crearse | in_draft |
| Evento | La acción que provoca el cambio | publish y unpublish |
| Transición | De qué estado a qué estado lleva cada evento | publish: de in_draft a published |
| Guard | Condición que debe cumplirse para que la transición ocurra | Que el artículo tenga título |
| Callback | Código que se ejecuta al cambiar de estado | Avisar a los suscriptores |
publish ocurre: si da false, publish! lanza AASM::InvalidTransition. La flecha discontinua no es un cambio de estado: es el callback que se ejecuta después de guardar.1. Instala la gema AASM en Rails
Este comando la añade al Gemfile y la instala en un solo paso:
bundle add aasm
Equivale a escribir gem "aasm" en el Gemfile y ejecutar bundle install.
2. Crea la columna del estado
El modelo Article necesita una columna de tipo string para guardar el estado. Si no existe, créala con una migración:
bin/rails generate migration AddStateToArticles state:string
bin/rails db:migrate
No le pongas un valor por defecto en la base de datos: la documentación de AASM avisa de que, si lo haces, no se ejecutan los callbacks del estado inicial al crear el objeto. Ya se encarga AASM de ponerlo.
Si llamas a la columna aasm_state, no hace falta indicarla en el modelo: es la que AASM usa por defecto.
3. Declara la máquina en el modelo
class Article < ApplicationRecord
include AASM
aasm column: :state do
state :in_draft, initial: true
state :published
event :publish do
transitions from: :in_draft, to: :published
end
event :unpublish do
transitions from: :published, to: :in_draft
end
end
end
- Hay dos estados:
in_draftypublished. - Todos los artículos nuevos empiezan en
in_draft(initial: true). - El evento
publishpasa dein_draftapublished, yunpublishhace el camino contrario.
4. Pruébalo en la consola
Abre la consola de Rails con bin/rails console:
article = Article.last
article.state # => "in_draft"
article.may_publish? # => true
article.publish! # cambia el estado y lo guarda en la base de datos
article.state # => "published"
article.published? # => true
article.may_publish? # => false: solo se publica desde in_draft
article.may_unpublish? # => true
article.publish!
# => AASM::InvalidTransition: Event 'publish' cannot transition from 'published'.
article.unpublish!
article.state # => "in_draft"
Métodos que genera AASM
| Método | Qué hace |
|---|---|
publish! |
Cambia el estado y guarda el registro |
publish |
Cambia el estado sin guardar (tendrás que llamar a save) |
may_publish? |
Dice si el evento se puede lanzar desde el estado actual |
published?, in_draft? |
Dicen si está en ese estado |
Article.published, Article.in_draft |
Scopes para buscar los registros de cada estado |
Article.aasm.states |
Lista los estados definidos |
article.aasm.events(permitted: true) |
Lista los eventos que se pueden lanzar ahora |
Primero pregunta conmay_; después cambia con!.
Las listas de estados y eventos son útiles para pintar botones solo con las acciones posibles:
Article.aasm.states.map(&:name) # => [:in_draft, :published]
Article.aasm.events.map(&:name) # => [:publish, :unpublish]
article = Article.create!(title: "Máquinas de estados")
article.aasm.events(permitted: true).map(&:name) # => [:publish]
article.aasm.permitted_transitions # => [{event: :publish, state: :published}]
Los scopes (Article.published) son consultas con nombre como las que se explican en Scopes en Ruby on Rails.
Guards: condiciones para cambiar de estado
Hasta aquí, cualquier borrador se puede publicar. Pero quizá no quieras publicar un artículo sin título. Un guard es una condición que se comprueba antes de la transición: si devuelve false, el cambio no ocurre. Es como el torno del metro: el paso existe, pero solo se abre si validas el billete.
event :publish do
transitions from: :in_draft, to: :published, guard: :has_title?
end
def has_title?
title.present?
end
sin_titulo = Article.create!(title: "")
sin_titulo.may_publish? # => false
sin_titulo.publish!
# => AASM::InvalidTransition: Event 'publish' cannot transition from 'in_draft'. Failed callback(s): [:has_title?].
may_publish? ya tiene en cuenta el guard, y el mensaje de error dice cuál ha fallado. Si necesitas varias condiciones, guards: [:has_title?, :has_body?] exige que se cumplan todas. También puedes escribirlo al estilo Ruby, con if: o unless:.
Un evento también puede partir de varios estados: from: admite una lista de estados de origen.
Callbacks: hacer algo al cambiar de estado
A menudo un cambio de estado tiene consecuencias: al publicar, avisar a los suscriptores; al enviar un pedido, mandar un correo. AASM ofrece callbacks en los estados (before_enter, after_enter…), en los eventos (before, after, after_commit…) y para todas las transiciones (after_all_transitions).
En un modelo de Rails, lo que salga del sistema (un correo, una llamada a otra API) va en after_commit: se ejecuta cuando el cambio ya está guardado en la base de datos, así no avisas de algo que luego se deshace. El modelo completo queda así:
class Article < ApplicationRecord
include AASM
# Quién avisa a los suscriptores. En los tests se cambia por un doble.
class_attribute :notifier, default: ->(article) { puts "Aviso enviado: #{article.title}" }
aasm column: :state do
state :in_draft, initial: true
state :published
event :publish, after_commit: :notify_subscribers do
transitions from: :in_draft, to: :published, guard: :has_title?
end
event :unpublish do
transitions from: :published, to: :in_draft
end
end
def has_title?
title.present?
end
def notify_subscribers
notifier.call(self) # aquí iría el envío real, por ejemplo un job
end
end
Article.create!(title: "Máquinas de estados").publish!
Aviso enviado: Máquinas de estados
El aviso no se escribe dentro de notify_subscribers, sino que se pide a notifier, un atributo de la clase. Así, en los tests se puede cambiar por un doble: una pieza falsa que no envía nada y solo apunta lo que le piden, como el maniquí que se usa en una prueba de choque en lugar de una persona.
Para ver el orden exacto en que se ejecutan todos los callbacks, el README de AASM tiene una lista completa. Si los callbacks de Rails te suenan, son la misma idea que se explica en Callbacks en Ruby on Rails, pero atados a un cambio de estado concreto.
Probar la máquina de estados con un test
Una máquina de estados es una lista de reglas: «un artículo nuevo es un borrador», «sin título no se publica», «no se publica dos veces». Cada regla cabe en un test, y esos tests son la mejor documentación de la máquina, porque se comprueban solos cada vez que los ejecutas.
AASM trae aserciones para Minitest, el framework de tests que Rails usa por defecto. Añade require "aasm/minitest" en test/test_helper.rb y escribe:
require "test_helper"
class ArticleTest < ActiveSupport::TestCase
setup do
@avisos = []
@notifier_real = Article.notifier
Article.notifier = ->(article) { @avisos << article.title } # el doble: apunta en vez de enviar
end
teardown do
Article.notifier = @notifier_real
end
test "un artículo nuevo empieza en borrador" do
assert_have_state Article.new, :in_draft
end
test "publish lo pasa de borrador a publicado" do
article = Article.new(title: "Máquinas de estados")
assert_transitions_from article, :in_draft, to: :published, on_event: :publish
end
test "no se puede publicar sin título" do
refute_event_allowed Article.new(title: ""), :publish
end
test "no se puede publicar dos veces" do
article = Article.create!(title: "Máquinas de estados")
article.publish!
assert_raises(AASM::InvalidTransition) { article.publish! }
end
test "unpublish lo devuelve a borrador" do
article = Article.create!(title: "Máquinas de estados")
article.publish!
article.unpublish!
assert_have_state article, :in_draft
end
test "al publicar avisa a los suscriptores" do
Article.create!(title: "Máquinas de estados").publish!
assert_equal ["Máquinas de estados"], @avisos
end
test "si falla el guard, no avisa" do
article = Article.create!(title: "")
assert_raises(AASM::InvalidTransition) { article.publish! }
assert_empty @avisos
end
end
En una aplicación Rails se ejecuta con bin/rails test test/models/article_test.rb. Al ejecutarlo con Minitest, la última línea de la salida es:
7 runs, 9 assertions, 0 failures, 0 errors, 0 skips
Fíjate en que no solo se prueba el camino feliz: los tests que más valen son los que comprueban lo que no debe pasar, porque son las reglas que alguien romperá sin querer. Si te inicias en los tests, empieza por Introducción al testing en Ruby; y si quieres escribir el test antes que el código, por TDD: qué es el desarrollo dirigido por tests.
Con RSpec
Si tu proyecto usa RSpec, añade require "aasm/rspec" en spec/spec_helper.rb y usa sus matchers:
RSpec.describe Article do
it "empieza en borrador" do
expect(Article.new).to have_state(:in_draft)
end
it "publish lo pasa de borrador a publicado" do
article = Article.new(title: "Máquinas de estados")
expect(article).to transition_from(:in_draft).to(:published).on_event(:publish)
end
it "no se puede publicar sin título" do
expect(Article.new(title: "")).not_to allow_event(:publish)
end
end
3 examples, 0 failures
Qué pasa si falla el guardado
publish! hace dos cosas: cambia el estado y guarda el registro. ¿Y si el guardado falla, por ejemplo por una validación? Desde AASM 6 se lanza una excepción y el estado guardado no cambia. Con una validación de longitud máxima de 10 caracteres en el título:
article = Article.create!(title: "Corto")
article.title = "Un título demasiado largo"
article.publish!
# => ActiveRecord::RecordInvalid: Validation failed: Title is too long (maximum is 10 characters)
article.reload.state # => "in_draft"
Si prefieres que los eventos devuelvan false en vez de lanzar errores, AASM tiene dos opciones: whiny_persistence: false para los fallos de guardado y whiny_transitions: false para las transiciones no permitidas. Úsalas con cuidado: un false que nadie comprueba es un error silencioso.
AASM sin Rails
AASM funciona con cualquier clase de Ruby: basta con include AASM. Sin base de datos, usa los eventos sin ! (pagar), porque no hay nada que guardar, y consulta el estado con aasm.current_state:
require "aasm"
class Pedido
include AASM
aasm do
state :pendiente, initial: true
state :pagado, :enviado
event :pagar do
transitions from: :pendiente, to: :pagado
end
event :enviar, after: :avisar do
transitions from: :pagado, to: :enviado
end
end
def avisar
puts "Pedido enviado (#{aasm.from_state} -> #{aasm.to_state})"
end
end
pedido = Pedido.new
p pedido.aasm.current_state
p pedido.may_enviar?
pedido.pagar
pedido.enviar
p pedido.aasm.current_state
p pedido.enviado?
:pendiente
false
Pedido enviado (pagado -> enviado)
:enviado
true
Un pedido pendiente no se puede enviar (may_enviar? es false): primero hay que pagarlo. Con whiny_transitions: false, el evento no permitido devuelve false en vez de lanzar el error:
aasm whiny_transitions: false do
# ...
end
pedido.pagar # => true
pedido.pagar # => false: ya estaba pagado
La idea de máquina de estados tampoco es exclusiva de Ruby: aquí la usamos para hacer multitarea en Arduino.
AASM o enum de Rails: cuándo usar cada uno
Rails trae enum, que también guarda un estado en una columna y genera métodos parecidos (published!, published?, Article.published). La diferencia es que enum solo sabe qué valores existen, no qué pasos entre ellos son válidos:
class Post < ApplicationRecord
enum :status, { in_draft: "in_draft", published: "published" }, default: :in_draft
end
post = Post.create!
post.published!
post.published! # ningún error: enum no sabe qué pasos son válidos
post.status # => "published"
| Necesitas… | Usa |
|---|---|
| Un campo con pocos valores posibles, que pasan de uno a otro libremente | enum |
| Reglas sobre qué cambios están permitidos | AASM |
| Condiciones para cambiar (guards) o acciones al cambiar (callbacks) | AASM |
| Varios estados con muchos eventos, que conviene ver de un vistazo | AASM |
Como regla práctica: si te sorprendes escribiendo if article.in_draft? antes de cada cambio, ya tienes una máquina de estados escondida, y AASM la hace explícita. Si el valor solo se lee y se cambia sin restricciones, enum basta y no añade una dependencia. Es una recomendación nuestra, no de la documentación de ninguna de las dos herramientas.
Errores típicos con AASM
- Poner un valor por defecto a la columna en la base de datos. Los callbacks del estado inicial no se ejecutan. Deja que AASM ponga el estado inicial.
- Usar
publishen vez depublish!en Rails. El estado cambia en memoria, pero no en la base de datos hasta que llames asave. Y, según el README, aunque lo guardes después, el callbackafter_commitno se ejecuta. - Cambiar la columna a mano (
article.update(state: "published")). Te saltas los guards y los callbacks. Cambia el estado siempre con un evento. - Lanzar el evento sin preguntar. Si el usuario puede pulsar «Publicar» dos veces, comprueba antes
may_publish?o capturaAASM::InvalidTransition. - Hacer efectos externos en
afteren vez deafter_commit. Si la transacción se deshace, ya habrás enviado el correo. - Leer el estado con
aasm_statesin mirar la columna.aasm_statesolo existe si la columna se llamaaasm_state, la que AASM usa por defecto. Concolumn: :state, como en este artículo, o en una clase de Ruby normal, usaaasm.current_state.
Qué cambia en AASM 6
AASM 6.0.0 salió el 5 de julio de 2026. Si vienes de la versión 5, lo que más te puede afectar:
- Necesita Ruby 3.0 o superior y, para Active Record, Rails 7.0 o superior.
whiny_persistencees ahoratruepor defecto: si al hacerpublish!falla el guardado, se lanza una excepción en vez de devolverfalse(lo has visto arriba).- Si usas varias máquinas con
namespace:, ya no se crean los métodos sin el sufijo del namespace.
Los detalles están en la guía de migración de la 5 a la 6.
Fuentes
Comprobado el 8 de noviembre de 2026:
- Documentación oficial de AASM: el README (guards, callbacks y su orden,
after_commitconafter_commit_everywhere,whiny_transitions, consulta de estados y eventos, aserciones de Minitest y matchers de RSpec, columnaaasm_statey el aviso sobre el valor por defecto), el CHANGELOG (6.0.0 del 5 de julio de 2026) y la guía de migración a la 6. La 6.0.0 es la versión más reciente en RubyGems. - ActiveRecord::Enum en la API de Rails 8.1.4.1.
Todo el código se ha ejecutado en Docker con la imagen ruby:latest (Ruby 4.0.9), aasm 6.0.0, activerecord 8.1.4.1, after_commit_everywhere 1.6.0, sqlite3 2.10.2 con una base de datos en memoria, minitest 6.1.0 y rspec-core 3.13.7. Los tests de Minitest se han ejecutado con ActiveSupport::TestCase y transacciones por test, como en una aplicación Rails. Las salidas mostradas son las reales. En lugar de una aplicación Rails completa se ha usado Active Record con un ApplicationRecord mínimo, así que los comandos bin/rails generate migration, bin/rails console y bin/rails test no se han ejecutado.