1 files changed, 27 insertions, 4 deletions
diff --git a/doc/development/testing_guide/testing_migrations_guide.md b/doc/development/testing_guide/testing_migrations_guide.md
index 8ee758177c3..a5bcb651d71 100644
--- a/doc/development/testing_guide/testing_migrations_guide.md
+++ b/doc/development/testing_guide/testing_migrations_guide.md
@@ -37,15 +37,37 @@ ensures proper isolation.
 
 To test an `ActiveRecord::Migration` class (i.e., a
 regular migration `db/migrate` or a post-migration `db/post_migrate`), you
-will need to manually `require` the migration file because it is not
-autoloaded with Rails. Example:
+will need to load the migration file by using the `require_migration!` helper
+method because it is not autoloaded by Rails.
+
+Example:
 
 ```ruby
-require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb')
+require 'spec_helper'
+
+require_migration!
+
+RSpec.describe ...
 ```
 
 ### Test helpers
 
+#### `require_migration!`
+
+Since the migration files are not autoloaded by Rails, you will need to manually
+load the migration file. To do so, you can use the `require_migration!` helper method
+which can automatically load the correct migration file based on the spec file name.
+
+For example, if your spec file is named as `populate_foo_column_spec.rb` then the
+helper method will try to load `${schema_version}_populate_foo_column.rb` migration file.
+
+In case there is no pattern between your spec file and the actual migration file,
+you can provide the migration file name without the schema version, like so:
+
+```ruby
+require_migration!('populate_foo_column')
+```
+
 #### `table`
 
 Use the `table` helper to create a temporary `ActiveRecord::Base`-derived model
@@ -110,7 +132,8 @@ migration. You can find the complete spec in
 
 ```ruby
 require 'spec_helper'
-require Rails.root.join('db', 'post_migrate', '20170526185842_migrate_pipeline_stages.rb')
+
+require_migration!
 
 RSpec.describe MigratePipelineStages do
   # Create test data - pipeline and CI/CD jobs.