DEV: Improve `upload_theme` system test helper (#23663)

What does this change do?

This change improves the `upload_theme` system test helper method by
automatically setting the uploaded theme as the default theme for the
site. This is to make it easier for users to use the theme instead of
having to fiddle with theme previews. The default behaviour of setting
the uploaded theme as the site's default theme can be disabled by
passing `false` to the `set_theme_as_default` keyword argument.

This change also introduces a new `upload_theme_component` system test
helper method for uploading theme components. The difference between the
`upload_theme` helper method is that the theme component is
automatically added to the site's default theme when uploaded. The theme
which the theme component is added to can be configured via the
`parent_theme_id` keyword argument.

For both methods, we also no longer require the path to the theme to be
provided. Instead both methods will look through the callstack and can
figure out the theme's directory based on the convention that the
theme's system tests are placed in the `spec/system` directory of the
theme folder. This change simplifies the usage of the methods for users
and helps to remove code like `upload_theme_component(File.expand_path("../..", __dir__))`.

spec/support/system_helpers.rb

@@ -22,8 +22,45 @@ module SystemHelpers
     expect(page).to have_content("Signed in to #{user.encoded_username} successfully")
   end
 
-  def upload_theme(theme_dir)
-    RemoteTheme.import_theme_from_directory(theme_dir)
+  # Uploads a theme from a directory.
+  #
+  # @param set_theme_as_default [Boolean] Whether to set the uploaded theme as the default theme for the site. Defaults to true.
+  #
+  # @return [Theme] The uploaded theme model given by `models/theme.rb`.
+  #
+  # @example Upload a theme and set it as default
+  #   upload_theme("/path/to/theme")
+  def upload_theme(set_theme_as_default: true)
+    theme = RemoteTheme.import_theme_from_directory(theme_dir_from_caller)
+
+    if theme.component
+      raise "Uploaded theme is a theme component, please use the `upload_theme_component` method instead."
+    end
+
+    theme.set_default! if set_theme_as_default
+    theme
+  end
+
+  # Uploads a theme component from a directory.
+  #
+  # @param parent_theme_id [Integer] The ID of the theme to add the theme component to. Defaults to `SiteSetting.default_theme_id`.
+  #
+  # @return [Theme] The uploaded theme model given by `models/theme.rb`.
+  #
+  # @example Upload a theme component
+  #   upload_theme_component("/path/to/theme_component")
+  #
+  # @example Upload a theme component and add it to a specific theme
+  #   upload_theme_component("/path/to/theme_component", parent_theme_id: 123)
+  def upload_theme_component(parent_theme_id: SiteSetting.default_theme_id)
+    theme = RemoteTheme.import_theme_from_directory(theme_dir_from_caller)
+
+    if !theme.component
+      raise "Uploaded theme is not a theme component, please use the `upload_theme` method instead."
+    end
+
+    Theme.find(parent_theme_id).child_themes << theme
+    theme
   end
 
   def setup_system_test
@@ -170,4 +207,14 @@ module SystemHelpers
       )
     end
   end
+
+  private
+
+  def theme_dir_from_caller
+    caller.each do |line|
+      if (split = line.split(%r{/spec/system/.+_spec.rb})).length > 1
+        return split.first
+      end
+    end
+  end
 end