rspec-system 2.1.2 → 2.2.0

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+2.2.0
+=====
+
+This feature release adds the ability to pass a node as a string to helpers, and improves documentation on multi-node support.
+
+#### Detailed Changes
+
+* Rename system_node to node in yarddoc (Ken Barber)
+* Add support for passing a node name as a string to the :node meta-parameter (Ken Barber)
+* Document basic multi-node usage (Ken Barber)
+* Created an FAQ section and included info about serverspec (Ken Barber)
+
 2.1.2
 =====
 

data/README.md

@@ -6,6 +6,26 @@ The goal here is to provide facilities to aid in the launching of tests nodes, c
 
 *Note:* This library is fairly new at the moment, so your mileage may vary. That said, if you're good at ruby and have an opinion, I'd appreciate patches and improvements to move this further torwards stability.
 
+### FAQ
+
+#### What is this tool, and why do I need it?
+
+`rspec-system` is a system testing tool that specializes in preparing test systems, running setup commands for a test and providing rspec helpers to assist with writing rspec assertions.
+
+In short, it tests software on real systems. For realz. It doesn't mock the execution of anything. So you would use this software, if you want more complete guarantees around the ability to run your software on a real operating system.
+
+For writing tests it uses the [rspec](https://www.relishapp.com/rspec) testing framework, used by many Ruby projects, your software however does not actually need to be written in Ruby - you just need to know a minimal amount of Ruby to write the tests.
+
+#### Can this tool be used to test Puppet?
+
+Yes it can. Check out the plugin: [rspec-system-serverspec](http://rubygems.org/gems/rspec-system-serverspec).
+
+#### How does this tool overlap with serverspec?
+
+`rspec-system` and `serverspec` are similar tools built to solve different testing perspectives. `serverspec` is aimed at validating a running environment with great tests and matchers that are made simple for administrators to write. `rspec-system` is an integration/system testing suite more then for built system validation. It is also used for testing a running environment, but its focus is more around testing system tools (such as Puppet for example) by launching nodes, setting up the software in question and performing tests on it. Thus `rspec-system` is appropriate for testing a piece of software, whereas `serverspec` is for validating a test or production system that has been built by some outside force.
+
+Of course the overlap is in what these tools do ultimately. `serverspec` logs into systems and runs commands to achieve its tests, and `rspec-system` is no different. However we have recognized `serverspec`'s strengths at the 'testing' end of the phase, so we have built a bridge so you can use `rspec-system` in your dev projects but benefit from the power of the `serverspec` tests and matchers: [rspec-system-serverspec](http://rubygems.org/gems/rspec-system-serverspec).
+
 ### Gem installation
 
 The intention is that this gem is used within your project as a development library.
@@ -94,6 +114,32 @@ The file must adhere to the Kwalify schema supplied in `resources/kwalify-schema
 * `sets -> [setname] -> nodes -> [name] -> prefab`: This relates to the prefabricated node template you wish to use. Currently this is the only way to launch a node. Look in `resources/prefabs.yml` for more details.
 * `default_set`: this is the default set to run if none are provided with `bundle exec rake spec:system`. This should be the most common platform normally.
 
+### Multi-node tests
+
+With `rspec-system` you can launch and perform tests and setup actions on multiple nodes.
+
+In your `.nodeset.yml` file you will need to define multiple nodes:
+
+    ---
+    sets:
+      'centos-59-x64-multinode':
+        nodes:
+          default_node: 'first.mydomain.vm':
+          'first.mydomain.vm':
+            prefab: 'centos-59-x64'
+          'second.mydomain.vm':
+            prefab: 'centos-59-x64'
+
+When you now run `rake spec:system` both nodes will launch.
+
+Tests need to be written specifically with multi-node in mind however. Normally, helpers will try to use the first (and thus default) node only when executed. If you wish to use a helper against a particular node instead, you can use the `:node` metaparameter to specify execution on a particular node.
+
+An example using the `shell` helper:
+
+    shell(:node => 'second.mydomain.vm', :command => 'hostname')
+
+This would execute the command `hostname` on node `second.mydomain.vm`.
+
 ### Prefabs
 
 Prefabs are 'pre-rolled' virtual images, for now its the only way to specify a template.
@@ -215,7 +261,8 @@ Right now we have two types of plugins, the framework is in a state of flux as t
 
 Libraries that provide test helpers, and setup helpers for testing development on the software in question.
 
-* [rspec-system-puppet](http://rubygems.org/gems/rspec-system-puppet)
+* [rspec-system-puppet](http://rubygems.org/gems/rspec-system-puppet) - Helpers for testing out Puppet plugins
+* [rspec-system-serverspec](http://rubygems.org/gems/rspec-system-serverspec) - Imports the serverspec helpers and matchers so they can be used in rspec-system.
 
 #### Node providers
 

data/examples/README.md

@@ -0,0 +1,6 @@
+Run the tests with:
+
+    bundle update
+    rake spec:system
+
+FYI: Some of these tests fail on purpose, so you can see how failures are handled. This is an example after-all :-).

data/lib/rspec-system/helper.rb

@@ -72,15 +72,21 @@ module RSpecSystem
         lazy = false
       end
 
-      opts = {
+      # Merge defaults and such
+      @opts = {
         :node => opts[:n] || dn,
         :n => opts[:node] || dn,
         :timeout => opts[:timeout] || 0,
         :lazy => lazy,
       }.merge(opts)
 
-      @opts = opts
-      r = result_data unless opts[:lazy]
+      # Try to figure out :node using the node helper if a string is passed
+      if @opts[:node].is_a? String
+        @opts[:n] = @opts[:node] = get_node_by_name(@opts[:node])
+      end
+
+      # Try to lookup result_data now, unless we are lazy
+      result_data unless @opts[:lazy]
 
       # If called as a block, yield the result as a block
       if block_given?
@@ -165,5 +171,15 @@ module RSpecSystem
     def default_node
       rspec_system_node_set.default_node
     end
+
+    # Returns a node by its name.
+    #
+    # To be used by helpers that wish to retrieve a node by its name.
+    #
+    # @param name [String] name of the node
+    # @return [RSpecSystem::Node] node found
+    def get_node_by_name(name)
+      rspec_system_node_set.nodes[name]
+    end
   end
 end

data/lib/rspec-system/helpers.rb

@@ -13,7 +13,7 @@ require 'rspec-system/helpers/rcp'
 #
 # The helpers themselves are split into two main groups, Queries:
 #
-# * +system_node+ - queries and returns node information
+# * +node+ - queries and returns node information
 #
 # And Actions:
 #
@@ -75,10 +75,10 @@ module RSpecSystem::Helpers
   #   @param options [Hash] options for command execution
   #   @option options [String] :command command to execute. Mandatory.
   #   @option options [String] :c alias for :command
-  #   @option options [RSpecSystem::Node] :node (defaults to what was defined
+  #   @option options [String,RSpecSystem::Node] :node (defaults to what was defined
   #     default in your YAML file, otherwise if there is only one node it uses
   #     that) specifies node to execute command on.
-  #   @option options [RSpecSystem::Node] :n alias for :node
+  #   @option options [String,RSpecSystem::Node] :n alias for :node
   #   @option options [Fixnum] :timeout seconds of time to allow before timing
   #     out. Defaults to 0 (not timeout).
   # @overload shell(command)

data/lib/rspec-system/helpers/rcp.rb

@@ -19,6 +19,14 @@ module RSpecSystem::Helpers
         :s => nil,
       }.merge(opts)
 
+      # Try to figure out :*_node using the node helper if a string is passed
+      if opts[:destination_node].is_a? String
+        opts[:d] = opts[:destination_node] = get_node_by_name(opts[:destination_node])
+      end
+      if opts[:source_node].is_a? String
+        opts[:s] = opts[:source_node] = get_node_by_name(opts[:source_node])
+      end
+
       super(opts, clr, &block)
     end
 

data/rspec-system.gemspec

@@ -2,7 +2,7 @@
 Gem::Specification.new do |s|
   # Metadata
   s.name        = "rspec-system"
-  s.version     = "2.1.2"
+  s.version     = "2.2.0"
   s.authors     = ["Ken Barber"]
   s.email       = ["info@puppetlabs.com"]
   s.homepage    = "https://github.com/puppetlabs/rspec-system"

data/spec/system/rcp_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper_system'
 
 describe "rcp:" do
-  it 'check rcp works with block matchers' do
+  it 'check it works with block matchers' do
     rcp(
       :sp => fixture_root + 'example_dir',
       :dp => '/tmp/example_destination1'
@@ -15,7 +15,7 @@ describe "rcp:" do
     end
   end
 
-  it 'check rcp works outside a block' do
+  it 'check it works outside a block' do
     r = rcp(
       :sp => fixture_root + 'example_dir',
       :dp => '/tmp/example_destination2'
@@ -27,4 +27,32 @@ describe "rcp:" do
       r.stdout.should =~ /Test content 1234/
     end
   end
+
+  it 'should support being passed a node as a string' do |r|
+    r = rcp(
+      :sp => fixture_root + 'example_dir',
+      :dp => '/tmp/example_destination3',
+      :destination_node => 'main',
+    )
+    r.success.should be_true
+
+    shell 'cat /tmp/example_destination3/example_file' do |r|
+      r.exit_code.should be_zero
+      r.stdout.should =~ /Test content 1234/
+    end
+  end
+
+  it 'should support being passed a node as an object' do |r|
+    r = rcp(
+      :sp => fixture_root + 'example_dir',
+      :dp => '/tmp/example_destination3',
+      :destination_node => node(:name => 'main'),
+    )
+    r.success.should be_true
+
+    shell 'cat /tmp/example_destination3/example_file' do |r|
+      r.exit_code.should be_zero
+      r.stdout.should =~ /Test content 1234/
+    end
+  end
 end

data/spec/system/shell_spec.rb

@@ -113,6 +113,18 @@ describe "shell:" do
     end
   end
 
+  it 'should support passing a node as an object' do
+    shell(:c => 'cat /etc/hosts', :n => node(:name => 'main')) do |r|
+      r.stdout.should =~ /localhost/
+    end
+  end
+
+  it 'should support passing a node as a string' do
+    shell(:c => 'cat /etc/hosts', :node => 'main') do |r|
+      r.stdout.should =~ /localhost/
+    end
+  end
+
   context 'legacy tests' do
     it 'cat /etc/hosts - test results using hash method' do
       shell 'cat /etc/hosts' do |r|

data/spec/unit/helper_spec.rb

@@ -23,6 +23,13 @@ describe 'RSpecSystem::Helper' do
       end
       block_exec.should be_true
     end
+
+    it 'should convert :node using get_node_by_name when passed as a string' do
+      RSpecSystem::Helper.any_instance.expects(:result_data)
+      RSpecSystem::Helper.any_instance.expects(:get_node_by_name).with('mynode').returns(node)
+      helper = RSpecSystem::Helper.new({:node => 'mynode'}, self)
+      helper.opts[:node].should == node
+    end
   end
 
   context '#refresh' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-system
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-24 00:00:00.000000000 Z
+date: 2013-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -142,6 +142,7 @@ files:
 - examples/.nodeset.yml
 - examples/.ruby-version
 - examples/Gemfile
+- examples/README.md
 - examples/Rakefile
 - examples/spec/spec_helper.rb
 - examples/spec/system/test1_spec.rb