Add support for $XDG_CONFIG_HOME/rspec/options

This is a XDG Base Directory Specification compatible alternative to
~/.rspec.

~/.rspec has higher precedence in order to reduce risk in cases where
users have a file like this dormant. It is unlikely, but this way the
risk is lower.

If $XDG_CONFIG_HOME is not set, it will fall back to ~/.config, per the
specification.

Other changes:

The "isolated home" example tag has been extended with a
`create_fixture_file` helper that also takes care to create the
directory where the file resides in, if it does not already exist.
Other file creations have been migrated to this method for consistency.

The method is only available when an example is tagged with
`:isolated_home => true`, for safety.

In case the developer running these tests have a custom $XDG_CONFIG_HOME
set, it is cleared out when using an isolated home so their real files
are not touched.

Author: Mange

Filtering.md

@@ -114,10 +114,10 @@ focus them.
 
 ## Options files and command line overrides
 
-Command line option declarations can be stored in `.rspec`, `~/.rspec`, or a custom
-options file. This is useful for storing defaults. For example, let's
-say you've got some slow specs that you want to suppress most of the
-time. You can tag them like this:
+Command line option declarations can be stored in `.rspec`, `~/.rspec`,
+`$XDG_CONFIG_HOME/rspec/options` or a custom options file. This is useful for
+storing defaults. For example, let's say you've got some slow specs that you
+want to suppress most of the time. You can tag them like this:
 
 ``` ruby
 RSpec.describe Something, :slow => true do

features/configuration/default_path.feature

@@ -5,7 +5,8 @@ Feature: Setting the default spec path
   This is supported by a `--default-path` option, which is set to `spec` by
   default. If you prefer to keep your specs in a different directory, or assign
   an individual file to `--default-path`, you can do so on the command line or
-  in a configuration file (`.rspec`, `~/.rspec`, or a custom file).
+  in a configuration file (`.rspec`, `~/.rspec`,
+  `$XDG_CONFIG_HOME/rspec/options`, or a custom file).
 
   **NOTE:** this option is not supported on `RSpec.configuration`, as it needs to be
   set before spec files are loaded.

features/configuration/read_options_from_file.feature

@@ -9,12 +9,18 @@ Feature: read command line configuration options from files
     * Project:  `./.rspec` (i.e. in the project's root directory, usually
       checked into the project)
 
-    * Global: `~/.rspec` (i.e. in the user's home directory)
+    * Global (HOME): `~/.rspec` (i.e. in the user's home directory)
 
-  Configuration options are loaded from `~/.rspec`, `.rspec`, `.rspec-local`,
-  command line switches, and the `SPEC_OPTS` environment variable (listed in
-  lowest to highest precedence; for example, an option in `~/.rspec` can be
-  overridden by an option in `.rspec-local`).
+    * Global (XDG): `$XDG_CONFIG_HOME/rspec/options` (i.e. in the user's
+      [the XDG Base Directory
+      Specification](https://specifications.freedesktop.org/basedir-spec/latest/)
+      config directory)
+
+  Configuration options are loaded from `$XDG_CONFIG_HOME/rspec/options`,
+  `~/.rspec`, `.rspec`, `.rspec-local`, command line switches, and the
+  `SPEC_OPTS` environment variable (listed in lowest to highest precedence; for
+  example, an option in `~/.rspec` can be overridden by an option in
+  `.rspec-local`).
 
   Scenario: Color set in `.rspec`
     Given a file named ".rspec" with:

lib/rspec/core/configuration.rb

@@ -9,10 +9,11 @@ module Core
 
     # Stores runtime configuration information.
     #
-    # Configuration options are loaded from `~/.rspec`, `.rspec`,
-    # `.rspec-local`, command line switches, and the `SPEC_OPTS` environment
-    # variable (listed in lowest to highest precedence; for example, an option
-    # in `~/.rspec` can be overridden by an option in `.rspec-local`).
+    # Configuration options are loaded from `$XDG_CONFIG_HOME/rspec/options`,
+    # `~/.rspec`, `.rspec`, `.rspec-local`, command line switches, and the
+    # `SPEC_OPTS` environment variable (listed in lowest to highest precedence;
+    # for example, an option in `~/.rspec` can be overridden by an option in
+    # `.rspec-local`).
     #
     # @example Standard settings
     #     RSpec.configure do |c|

lib/rspec/core/configuration_options.rb

@@ -4,8 +4,9 @@
 module RSpec
   module Core
     # Responsible for utilizing externally provided configuration options,
-    # whether via the command line, `.rspec`, `~/.rspec`, `.rspec-local`
-    # or a custom options file.
+    # whether via the command line, `.rspec`, `~/.rspec`,
+    # `$XDG_CONFIG_HOME/rspec/options`, `.rspec-local` or a custom options
+    # file.
     class ConfigurationOptions
       # @param args [Array<String>] command line arguments
       def initialize(args)
@@ -118,7 +119,11 @@ def load_formatters_into(config)
       end
 
       def file_options
-        custom_options_file ? [custom_options] : [global_options, project_options, local_options]
+        if custom_options_file
+          [custom_options]
+        else
+          [global_xdg_options, global_options, project_options, local_options]
+        end
       end
 
       def env_options
@@ -150,6 +155,10 @@ def global_options
         @global_options ||= options_from(global_options_file)
       end
 
+      def global_xdg_options
+        @global_xdg_options ||= options_from(global_xdg_options_file)
+      end
+
       def options_from(path)
         args = args_from_options_file(path)
         parse_args_ignoring_files_or_dirs_to_run(args, path)
@@ -195,6 +204,16 @@ def global_options_file
         nil
         # :nocov:
       end
+
+      def global_xdg_options_file
+        xdg_config_home = ENV.fetch("XDG_CONFIG_HOME", "~/.config")
+        File.join(File.expand_path(xdg_config_home), "rspec", "options")
+      rescue ArgumentError
+        # :nocov:
+        RSpec.warning "Unable to find $XDG_CONFIG_HOME/rspec/options because the HOME environment variable is not set"
+        nil
+        # :nocov:
+      end
     end
   end
 end

spec/rspec/core/configuration_options_spec.rb

@@ -412,6 +412,14 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
       end
     end
 
+    context "defined in $XDG_CONFIG_HOME/rspec/options" do
+      it "mentions the file name in the error so users know where to look for it" do
+        file_name = File.expand_path("~/.config/rspec/options")
+        create_fixture_file(file_name, "--foo_bar")
+        expect_parsing_to_fail_mentioning_source(file_name)
+      end
+    end
+
     context "defined in SPEC_OPTS" do
       it "mentions ENV['SPEC_OPTS'] as the source in the error so users know where to look for it" do
         with_env_vars 'SPEC_OPTS' => "--foo_bar" do
@@ -440,25 +448,43 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
     end
   end
 
-  describe "sources: ~/.rspec, ./.rspec, ./.rspec-local, custom, CLI, and SPEC_OPTS" do
-    it "merges global, local, SPEC_OPTS, and CLI" do
-      File.open("./.rspec", "w") {|f| f << "--require some_file"}
-      File.open("./.rspec-local", "w") {|f| f << "--format global"}
-      File.open(File.expand_path("~/.rspec"), "w") {|f| f << "--force-color"}
+  describe "sources: $XDG_CONFIG_HOME/rspec/options, ~/.rspec, ./.rspec, ./.rspec-local, custom, CLI, and SPEC_OPTS" do
+    it "merges both global, local, SPEC_OPTS, and CLI" do
+      create_fixture_file("./.rspec", "--require some_file")
+      create_fixture_file("./.rspec-local", "--format global")
+      create_fixture_file("~/.rspec", "--force-color")
+      create_fixture_file("~/.config/rspec/options", "--order defined")
       with_env_vars 'SPEC_OPTS' => "--example 'foo bar'" do
         options = parse_options("--drb")
         expect(options[:color_mode]).to eq(:on)
         expect(options[:requires]).to eq(["some_file"])
         expect(options[:full_description]).to eq([/foo\ bar/])
         expect(options[:drb]).to be_truthy
         expect(options[:formatters]).to eq([['global']])
+        expect(options[:order]).to eq("defined")
+      end
+    end
+
+    it "uses $XDG_CONFIG_HOME environment variable when set to find XDG global options" do
+      create_fixture_file("~/.config/rspec/options", "--format default_xdg")
+      create_fixture_file("~/.custom-config/rspec/options", "--format overridden_xdg")
+
+      with_env_vars 'XDG_CONFIG_HOME' => "~/.custom-config" do
+        options = parse_options()
+        expect(options[:formatters]).to eq([['overridden_xdg']])
+      end
+
+      without_env_vars 'XDG_CONFIG_HOME' do
+        options = parse_options()
+        expect(options[:formatters]).to eq([['default_xdg']])
       end
     end
 
     it 'ignores file or dir names put in one of the option files or in SPEC_OPTS, since those are for persistent options' do
-      File.open("./.rspec", "w") { |f| f << "path/to/spec_1.rb" }
-      File.open("./.rspec-local", "w") { |f| f << "path/to/spec_2.rb" }
-      File.open(File.expand_path("~/.rspec"), "w") {|f| f << "path/to/spec_3.rb"}
+      create_fixture_file("./.rspec", "path/to/spec_1.rb" )
+      create_fixture_file("./.rspec-local", "path/to/spec_2.rb" )
+      create_fixture_file("~/.rspec", "path/to/spec_3.rb")
+      create_fixture_file("~/.config/rspec/options", "path/to/spec_4.rb")
       with_env_vars 'SPEC_OPTS' => "path/to/spec_4.rb" do
         options = parse_options()
         expect(options[:files_or_directories_to_run]).to eq([])
@@ -472,13 +498,14 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
     end
 
     it "prefers CLI over file options" do
-      File.open("./.rspec", "w") {|f| f << "--format project"}
-      File.open(File.expand_path("~/.rspec"), "w") {|f| f << "--format global"}
+      create_fixture_file("./.rspec", "--format project")
+      create_fixture_file("~/.rspec", "--format global")
+      create_fixture_file("~/.config/rspec/options", "--format xdg")
       expect(parse_options("--format", "cli")[:formatters]).to eq([['cli']])
     end
 
     it "prefers CLI over file options for filter inclusion" do
-      File.open("./.rspec", "w") {|f| f << "--tag ~slow"}
+      create_fixture_file("./.rspec", "--tag ~slow")
       opts = config_options_object("--tag", "slow")
       config = RSpec::Core::Configuration.new
       opts.configure(config)
@@ -487,14 +514,15 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
     end
 
     it "prefers project file options over global file options" do
-      File.open("./.rspec", "w") {|f| f << "--format project"}
-      File.open(File.expand_path("~/.rspec"), "w") {|f| f << "--format global"}
+      create_fixture_file("./.rspec", "--format project")
+      create_fixture_file("~/.rspec", "--format global")
+      create_fixture_file("~/.config/rspec/options", "--format xdg")
       expect(parse_options[:formatters]).to eq([['project']])
     end
 
     it "prefers local file options over project file options" do
-      File.open("./.rspec-local", "w") {|f| f << "--format local"}
-      File.open("./.rspec", "w") {|f| f << "--format global"}
+      create_fixture_file("./.rspec-local", "--format local")
+      create_fixture_file("./.rspec", "--format global")
       expect(parse_options[:formatters]).to eq([['local']])
     end
 
@@ -510,16 +538,17 @@ def expect_parsing_to_fail_mentioning_source(source, options=[])
 
     context "with custom options file" do
       it "ignores project and global options files" do
-        File.open("./.rspec", "w") {|f| f << "--format project"}
-        File.open(File.expand_path("~/.rspec"), "w") {|f| f << "--format global"}
-        File.open("./custom.opts", "w") {|f| f << "--force-color"}
+        create_fixture_file("./.rspec", "--format project")
+        create_fixture_file("~/.rspec", "--format global")
+        create_fixture_file("~/.config/rspec/options", "--format xdg")
+        create_fixture_file("./custom.opts", "--force-color")
         options = parse_options("-O", "./custom.opts")
         expect(options[:format]).to be_nil
         expect(options[:color_mode]).to eq(:on)
       end
 
       it "parses -e 'full spec description'" do
-        File.open("./custom.opts", "w") {|f| f << "-e 'The quick brown fox jumps over the lazy dog'"}
+        create_fixture_file("./custom.opts", "-e 'The quick brown fox jumps over the lazy dog'")
         options = parse_options("-O", "./custom.opts")
         expect(options[:full_description]).to eq([/The\ quick\ brown\ fox\ jumps\ over\ the\ lazy\ dog/])
       end

spec/support/isolated_home_directory.rb

@@ -1,20 +1,35 @@
 require 'tmpdir'
 require 'fileutils'
+require 'pathname'
 
 RSpec.shared_context "isolated home directory" do
   around do |ex|
     Dir.mktmpdir do |tmp_dir|
-      original_home = ENV['HOME']
-      begin
-        ENV['HOME'] = tmp_dir
-        ex.call
-      ensure
-        ENV['HOME'] = original_home
+      # If user has a custom $XDG_CONFIG_HOME, also clear that out when
+      # changing $HOME so tests don't touch the user's real config files.
+      without_env_vars "XDG_CONFIG_HOME" do
+        with_env_vars "HOME" => tmp_dir do
+          ex.call
+        end
       end
     end
   end
 end
 
+module HomeFixtureHelpers
+  def create_fixture_file(file_name, contents)
+    path = Pathname.new(file_name).expand_path
+    if !path.exist?
+      path.dirname.mkpath
+      path.write(contents)
+    else
+      # Abort just in case we're about to destroy something important.
+      raise "File at #{path} already exists!"
+    end
+  end
+end
+
 RSpec.configure do |c|
   c.include_context "isolated home directory", :isolated_home => true
+  c.include HomeFixtureHelpers, :isolated_home => true
 end