Merge pull request rails#54308 from tiramizoo/assert_dom_preference

Prefer assert_dom over assert_select
Shopify · Jan 21, 2025 · 44988c1 · 44988c1
2 parents 241e125 + d615371
commit 44988c1
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 11 deletions.
diff --git a/actionpack/lib/action_dispatch/testing/integration.rb b/actionpack/lib/action_dispatch/testing/integration.rb
@@ -549,7 +549,7 @@ def method_missing(method, ...)
   #         https!(false)
   #         get "/articles/all"
   #         assert_response :success
-  #         assert_select 'h1', 'Articles'
+  #         assert_dom 'h1', 'Articles'
   #       end
   #     end
   #
@@ -588,7 +588,7 @@ def method_missing(method, ...)
   #           def browses_site
   #             get "/products/all"
   #             assert_response :success
-  #             assert_select 'h1', 'Products'
+  #             assert_dom 'h1', 'Products'
   #           end
   #         end
   #

diff --git a/guides/source/testing.md b/guides/source/testing.md
@@ -1334,18 +1334,16 @@ require "test_helper"
 class BlogFlowTest < ActionDispatch::IntegrationTest
   test "can see the welcome page" do
     get "/"
-    assert_select "h1", "Welcome#index"
+    assert_dom "h1", "Welcome#index"
   end
 end
 ```
 
 If you visit the root path, you should see `welcome/index.html.erb` rendered for
 the view. So this assertion should pass.
 
-NOTE: The assertion `assert_select` is available in integration tests to check
-the presence of key HTML elements and their content. It is similar to
-`assert_dom`, which should be used when [testing views](#testing-views) as
-outlined in the section below.
+NOTE: The assertion `assert_dom` (aliased to `assert_select`) is available in integration tests to check
+the presence of key HTML elements and their content.
 
 #### Creating Articles Integration
 
@@ -1439,7 +1437,7 @@ class UsersTest < ApplicationSystemTestCase
   # test "visiting the index" do
   #   visit users_url
   #
-  #   assert_select "h1", text: "Users"
+  #   assert_dom "h1", text: "Users"
   # end
 end
 ```
@@ -1578,7 +1576,7 @@ require "application_system_test_case"
 class ArticlesTest < ApplicationSystemTestCase
   test "viewing the index" do
     visit articles_path
-    assert_select "h1", text: "Articles"
+    assert_selector "h1", text: "Articles"
   end
 end
 ```
@@ -1654,7 +1652,7 @@ require "mobile_system_test_case"
 class PostsTest < MobileSystemTestCase
   test "visiting the index" do
     visit posts_url
-    assert_select "h1", text: "Posts"
+    assert_selector "h1", text: "Posts"
   end
 end
 ```
@@ -1671,7 +1669,7 @@ which can be used in system tests.
 | `assert_current_path(string, **options)`                         | Asserts that the page has the given path. |
 | `assert_field(locator = nil, **options, &optional_filter_block)` | Checks if the page has a form field with the given label, name or id. |
 | `assert_link(locator = nil, **options, &optional_filter_block)`  | Checks if the page has a link with the given text or id. |
-| `assert_select(*args, &optional_filter_block)`                   | Asserts that a given selector is on the page. |
+| `assert_selector(*args, &optional_filter_block)`                 | Asserts that a given selector is on the page. |
 | `assert_table(locator = nil, **options, &optional_filter_block`  | Checks if the page has a table with the given id or caption. |
 | `assert_text(type, text, **options)`                             | Asserts that the page has the given text content. |