Nivel inicial12 min de lectura · Publicado el

Gema AASM: máquina de estados en Ruby on Rails

Máquina de estados con AASM: in_draft pasa a published con publish y vuelve con unpublish; publicar dos veces da AASM::InvalidTransition. AASM: solo pasos permitidosrubentejera.com in_draftpublishedpublishunpublishpublicar dos vecesAASM::InvalidTransition
El artículo solo cambia de estado por los eventos permitidos: publish lo lleva de in_draft a published y unpublish lo devuelve. Publicar dos veces no es un paso permitido y da AASM::InvalidTransition.

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
Máquina de estados del artículo con AASM: empieza en in_draft (borrador, initial: true). El evento publish pasa por el guard has_title?: si el artículo no tiene título devuelve false, no cambia de estado y publish! lanza AASM::InvalidTransition; si lo tiene, pasa a published (publicado). El evento unpublish vuelve de published a in_draft. Después de guardar la publicación, el callback after_commit llama a notify_subscribers, que avisa a los suscriptores.
Las piezas de la tabla en el ejemplo que montamos abajo: en ámbar, los dos estados; las flechas continuas, los eventos, y el rombo magenta, el guard que decide si 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_draft y published.
  • Todos los artículos nuevos empiezan en in_draft (initial: true).
  • El evento publish pasa de in_draft a published, y unpublish hace 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 con may_; 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

  1. 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.
  2. Usar publish en vez de publish! en Rails. El estado cambia en memoria, pero no en la base de datos hasta que llames a save. Y, según el README, aunque lo guardes después, el callback after_commit no se ejecuta.
  3. Cambiar la columna a mano (article.update(state: "published")). Te saltas los guards y los callbacks. Cambia el estado siempre con un evento.
  4. Lanzar el evento sin preguntar. Si el usuario puede pulsar «Publicar» dos veces, comprueba antes may_publish? o captura AASM::InvalidTransition.
  5. Hacer efectos externos en after en vez de after_commit. Si la transacción se deshace, ya habrás enviado el correo.
  6. Leer el estado con aasm_state sin mirar la columna. aasm_state solo existe si la columna se llama aasm_state, la que AASM usa por defecto. Con column: :state, como en este artículo, o en una clase de Ruby normal, usa aasm.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_persistence es ahora true por defecto: si al hacer publish! falla el guardado, se lanza una excepción en vez de devolver false (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_commit con after_commit_everywhere, whiny_transitions, consulta de estados y eventos, aserciones de Minitest y matchers de RSpec, columna aasm_state y 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.