diff --git a/actiontext/lib/action_text/fixture_set.rb b/actiontext/lib/action_text/fixture_set.rb
index 8f3471d28a..db9fd3c2c5 100644
--- a/actiontext/lib/action_text/fixture_set.rb
+++ b/actiontext/lib/action_text/fixture_set.rb
@@ -1,7 +1,56 @@
# frozen_string_literal: true
module ActionText
+ # Fixtures are a way of organizing data that you want to test against; in
+ # short, sample data.
+ #
+ # To learn more about fixtures, read the
+ # {ActiveRecord::FixtureSet}[rdoc-ref:ActiveRecord::FixtureSet] documentation.
+ #
+ # === YAML
+ #
+ # Like other Active Record-backed models, ActionText::RichText records inherit
+ # from ActiveRecord::Base instances and therefore can be populated by
+ # fixtures.
+ #
+ # Consider a hypothetical Article model class, its related fixture
+ # data, as well as fixture data for related ActionText::RichText records:
+ #
+ # # app/models/article.rb
+ # class Article < ApplicationRecord
+ # has_rich_text :content
+ # end
+ #
+ # # tests/fixtures/articles.yml
+ # first:
+ # title: An Article
+ #
+ # # tests/fixtures/action_text/rich_texts.yml
+ # first_content:
+ # record: first (Article)
+ # name: content
+ # body:
Hello, world.
+ #
+ # When processed, Active Record will insert database records for each fixture
+ # entry and will ensure the Action Text relationship is intact.
class FixtureSet
+ # Fixtures support Action Text attachments as part of their body
+ # HTML.
+ #
+ # === Examples
+ #
+ # For example, consider a second Article record that mentions the
+ # first as part of its content HTML:
+ #
+ # # tests/fixtures/articles.yml
+ # second:
+ # title: Another Article
+ #
+ # # tests/fixtures/action_text/rich_texts.yml
+ # second_content:
+ # record: second (Article)
+ # name: content
+ # body: Hello, <%= ActionText::FixtureSet.attachment("artcles", :first) %>
def self.attachment(fixture_set_name, label, column_type: :integer)
signed_global_id = ActiveRecord::FixtureSet.signed_global_id fixture_set_name, label,
column_type: column_type, for: ActionText::Attachable::LOCATOR_NAME
diff --git a/guides/source/testing.md b/guides/source/testing.md
index 432a15fd8d..92b2739abd 100644
--- a/guides/source/testing.md
+++ b/guides/source/testing.md
@@ -640,11 +640,18 @@ about:
# fixtures/articles.yml
first:
title: Welcome to Rails!
- body: Hello world!
category: about
```
-Notice the `category` key of the `first` article found in `fixtures/articles.yml` has a value of `about`. This tells Rails to load the category `about` found in `fixtures/categories.yml`.
+```yaml
+# fixtures/action_text/rich_texts.yml
+first_content:
+ record: first (Article)
+ name: content
+ body: Hello, from a fixture
+```
+
+Notice the `category` key of the `first` Article found in `fixtures/articles.yml` has a value of `about`, and that the `record` key of the `first_content` entry found in `fixtures/action_text/rich_texts.yml` has a value of `first (Article)`. This hints to Active Record to load the Category `about` found in `fixtures/categories.yml` for the former, and Action Text to load the Article `first` found in `fixtures/articles.yml` for the latter.
NOTE: For associations to reference one another by name, you can use the fixture name instead of specifying the `id:` attribute on the associated fixtures. Rails will auto assign a primary key to be consistent between runs. For more information on this association behavior please read the [Fixtures API documentation](https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html).