module Radius::Spec::Tempfile

Temporary file helpers

These helpers are meant to ease the creation of temporary files to either stub the data out or provide a location for data to be saved then verified.

In the case of file stubs, using these helpers allows you to co-locate the file data with the specs. This makes it easy for someone to read the spec and understand the test case; instead of having to find a fixture file and look at its data. This also makes it easy to change the data between specs, allowing them to focus on just what they need.

To make these helpers available require them after the gem:

“`ruby require 'radius/spec' require 'radius/spec/tempfile' “`

### Including Helpers in Specs

There are multiple ways you can use these helpers. Which method you choose depends on how much perceived magic/syntactic sugar you want:

- call the helpers directly on the module
- manually include the helper methods in the specs
- use metadata to auto load this feature and include it in the specs

When using the metadata option you do not need to explicitly require the module. This gem registers metadata with the RSpec configuration when it loads and `RSpec` is defined. When the matching metadata is first used it will automatically require and include the helpers.

Any of following metadata will include the factory helpers:

- `:tempfile`
- `:tmpfile`

@example use a helper directly in specs

require 'radius/spec/tempfile'

RSpec.describe AnyClass do
  it "includes the file helpers" do
    Radius::Spec::Tempfile.using_tempfile do |pathname|
      code_under_test pathname
      expect(pathname.read).to eq "Any written data"
    end
  end
end

@example manually include the helpers

require 'radius/spec/tempfile'

RSpec.describe AnyClass do
  include Radius::Spec::Tempfile
  it "includes the file helpers" do
    using_tempfile do |pathname|
      code_under_test pathname
      expect(pathname.read).to eq "Any written data"
    end
  end
end

@example use metadata to auto include the helpers

RSpec.describe AnyClass do
  it "includes the file helpers", :tempfile do
    using_tempfile do |pathname|
      code_under_test pathname
      expect(pathname.read).to eq "Any written data"
    end
  end
end

@since 0.5.0

Public Instance Methods

using_tempfile(*args, data: nil, **kwargs) { |Pathname(path)| ... } click to toggle source

Convenience wrapper for managaing temporary files.

This creates a temporary file and yields its path to the provided block. When the block returns the temporary file is deleted.

### Optional Parameters

The block is required. All other parameters are optional. All parameters except `data` are Ruby version dependent and will be forwarded directly to the stdlib's {ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create `Tempfile.create`}. The when the `data` parameter is provided it's contents will be written to the temporary file prior to yielding to the block.

@example creating a tempfile to pass to code

def write_hello_world(filepath)
  File.write filepath, "Hello World"
end

Radius::Spec::Tempfile.using_tempfile do |pathname|
  write_hello_world pathname
end

@example creating a file stub

stub_data = "Any file stub data text."
Radius::Spec::Tempfile.using_tempfile(data: stub_data) do |stubpath|
  # File.read(stubpath)
  # => "Any file stub data text."
  code_under_test stubpath
end

@example creating a file stub inline

Radius::Spec::Tempfile.using_tempfile(data: <<~TEXT) do |stubpath|
  Any file stub data text.
TEXT
  # File.read(stubpath)
  # => "Any file stub data text.\n"
  code_under_test stubpath
end

@example creating a file stub inline without trailing newline

Radius::Spec::Tempfile.using_tempfile(data: <<~TEXT.chomp) do |stubpath|
  Any file stub data text.
TEXT
  # File.read(stubpath)
  # => "Any file stub data text."
  code_under_test stubpath
end

@example writing binary data inline

Radius::Spec::Tempfile.using_tempfile(encoding: Encoding::BINARY, data: <<~BIN.chomp) do |binpath|
  \xC8\x90\xC5\x9D\xE1\xB9\x95\xC4\x93\xC4\x89
BIN
  # File.read(binpath)
  # => "Ȑŝṕēĉ"
  code_under_test binpath
end

@param args [Object] addition file creation options

Passed directly to {https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create
`Tempfile.create`}; see the stdlib docs for details on available
options.

@param data [String] stub data to write to the file before yielding @param kwargs [Hash{Symbol => Object}] addition file creation options

Passed directly to {https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html#method-c-create
`Tempfile.create`}; see the stdlib docs for details on available
options.

@yieldparam pathname [Pathname] {ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html path}

of the created temporary file

@note A block must be provided @see ruby-doc.org/stdlib/libdoc/pathname/rdoc/Pathname.html Pathname @see ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html Tempfile

# File lib/radius/spec/tempfile.rb, line 152
def using_tempfile(*args, data: nil, **kwargs)
  args << 'tmpfile' if args.empty?
  ::Tempfile.create(*args, **kwargs) do |f|
    f.write(data)
    f.close
    yield Pathname(f.path)
  end
end