The ruby_exe helper provides a wrapper for invoking the same Ruby interpreter as the one running the specs and getting the output from running the code. If code is a file that exists, it will be run. Otherwise, code should be Ruby code that will be run with the -e command line option. For example:
ruby_exe('path/to/some/file.rb')
will be executed as
`#{RUBY_EXE} #{'path/to/some/file.rb'}`
while
ruby_exe('puts "hello, world."')
will be executed as
`#{RUBY_EXE} -e #{'puts "hello, world."'}`
The ruby_exe helper also accepts an options hash with two keys: :options and :args. For example:
ruby_exe('file.rb', :options => "-w", :args => "> file.txt")
will be executed as
`#{RUBY_EXE} -w #{'file.rb'} > file.txt`
If nil is passed for the first argument, the command line will be built only from the options hash.
The RUBY_EXE constant can be set explicitly since the value is used each time ruby_exe is invoked. The mspec runner script will set ENV[‘RUBY_EXE’] to the name of the executable used to invoke the mspec-run script. The value of RUBY_EXE will be constructed as follows:
1. the value of ENV['RUBY_EXE'] 2. an explicit value based on RUBY_NAME 3. cwd/(RUBY_NAME + $(EXEEXT) || $(exeext) || '') 4. $(bindir)/$(RUBY_INSTALL_NAME)
The value will only be used if the file exists and is executable.
These 4 ways correspond to the following scenarios:
1. Using the MSpec runner scripts, the name of the executable is explicitly passed by ENV['RUBY_EXE'] so there is no ambiguity. Otherwise, if using RSpec (or something else) 2. Running the specs while developing an alternative Ruby implementation. This explicitly names the executable in the development directory based on the value of RUBY_NAME, which is probably initialized from the value of RUBY_ENGINE. 3. Running the specs within the source directory for some implementation. (E.g. a local build directory.) 4. Running the specs against some installed Ruby implementation.
RUBY_EXE | = | resolve_ruby_exe or raise Exception, "Unable to find a suitable ruby executable." |
NO_MATCHER_GIVEN | = | Object.new |
object_id | -> | __mspec_object_id__ |
Convenience helper for altering ARGV. Saves the value of ARGV and sets it to args. If a block is given, yields to the block and then restores the value of ARGV. The previously saved value of ARGV can be restored by passing +:restore+. The former is useful in a single spec. The latter is useful in before/after actions. For example:
describe "This" do before do argv ['a', 'b'] end after do argv :restore end it "does something" do # do something end end describe "That" do it "does something" do argv ['a', 'b'] do # do something end end end
In some cases, libraries will modify another Ruby method‘s behavior. The specs for the method‘s behavior will then fail if that library is loaded. This guard will not run if any of the specified constants exist in Object.constants.
Helper to handle String encodings. The str and encoding parameters must be Strings and an ArgumentError will be raised if not. This ensures that the encode() helper can be used regardless of whether Encoding exits. The helper is a no-op (i.e. passes through str unmodified) if the :encoding feature is not enabled (see with_feature guard). If the :encoding feature is enabled, str.force_encoding(encoding) is called.
Returns the Enumerator class (either Enumerator or Enumerable::Enumerator) depending of the version.
Returns the name of a fixture file by adjoining the directory of the dir argument with "fixtures" and the contents of the args array. For example,
+dir+ == "some/path"
and
+args+ == ["dir", "file.txt"]
then the result is the expanded path of
"some/fixtures/dir/file.txt".
This helper simplifies passing file access modes regardless of whether the :encoding feature is enabled. Only the access specifier itself will be returned if :encoding is not enabled. Otherwise, the full mode string will be returned (i.e. the helper is a no-op).
Opens a file specified by the string the matcher is called on and compares the data passed to the matcher with the contents of the file. Expects to match the first N bytes of the file with data. For example, suppose @name is the name of a file:
@name.should have_data("123")
passes if the file @name has "123" as the first 3 bytes. The file can contain more bytes than data. The extra bytes do not affect the result.
Helper for syntax-sensitive specs. The specs should be placed in a file in the versions subdirectory. For example, suppose language/method_spec.rb contains specs whose syntax depends on the Ruby version. In the language/method_spec.rb use the helper as follows:
language_version __FILE__, "method"
Then add a file "language/versions/method_1.8.rb" for the specs that are syntax-compatible with Ruby 1.8.x.
The most version-specific file will be loaded. If the version is 1.8.6, "method_1.8.6.rb" will be loaded if it exists, otherwise "method_1.8.rb" will be loaded if it exists.
Creates a "bare" file descriptor (i.e. one that is not associated with any Ruby object). The file descriptor can safely be passed to IO.new without creating a Ruby object alias to the fd.
Recursively removes all files and directories in path if path is a directory. Removes the file if path is a file.
This guard wraps specs for one or more particular implementations. See the unspecified guard for further documentation.
Creates a file name. Creates the directory for name if it does not exist.
This guard wraps one or more specified_on guards to group them and document the specs. The purpose of the guard is for situations where MRI either does not specify Ruby behavior or where MRI‘s behavior is all but impossible to spec, for example due to relying on platform-specific behavior that is not easily testable from Ruby code. In such cases, it may be desirable for implementations to explore a specified set of behaviors that are explicitly documented in the specs.
unspecified do specified_on :rubinius, :ironruby do it "returns true when passed :foo" do # ... end it "returns false when passed :bar" do # ... end end specified_on :jruby do it "returns true when passed :bar" do # ... end end end
Note that these guards do not change the policy of the compliant_on, not_compliant_on, deviates_on, extended_on, and not_supported_on guards.
Provides better documentation in the specs by naming sets of features that work together as a whole. Examples include :encoding, :fiber, :continuation, :fork.
Usage example:
with_feature :encoding do # specs for a method that provides aspects # of the encoding feature end
Multiple features must all be enabled for the guard to run:
with_feature :one, :two do # these specs will run if features :one AND # :two are enabled. end
The implementation must explicitly enable a feature by adding code like the following to the .mspec configuration file:
MSpec.enable_feature :encoding