raml_ruby 0.1.1

data/test/raml/body_spec.rb

@@ -0,0 +1,268 @@
+require_relative 'spec_helper'
+
+describe Raml::Body do
+  let (:media_type) { 'text/xml' }
+  let (:body_data ) {
+    YAML.load(%q(
+      schema: |
+        {
+          "$schema": "http://json-schema.org/draft-03/schema#",
+          "properties": {
+              "input": {
+                  "required": false,
+                  "type": "string"
+              }
+          },
+          "required": false,
+          "type": "object"
+        }
+    ))
+  }  
+  let(:form_body_data) {
+    YAML.load(%q(
+      formParameters:
+        param:
+          type: string
+    ))
+  }
+  let(:root) { Raml::Root.new 'title' => 'x', 'baseUri' => 'http://foo.com', 'schemas' => [{'Job' => 'xxx'}] }
+
+  subject { Raml::Body.new media_type, body_data, root }
+  
+  describe '#initialize' do
+    context 'when the media type is valid' do
+      it "inits body with media_type" do
+        expect( subject.media_type ).to eq media_type
+      end
+    end
+    context 'when the media type is invalid' do
+      let(:media_type) { 'foo' }
+      it { expect { subject }.to raise_error Raml::InvalidMediaType }
+    end
+
+    context 'when the body is not a web form' do
+      context 'when the schema property is valid schema' do
+        it "inits body with schema" do
+          expect( subject.schema ).to be_an Raml::Schema
+        end
+      end
+      context 'when the schema property is valid schema reference' do
+        let (:body_data ) { { 'schema' => 'Job' } }
+        it "inits body with schema" do
+          expect( subject.schema ).to be_an Raml::SchemaReference
+        end
+      end
+      context 'when the schema property is not a string' do
+        let (:body_data ) { { 'schema' => 1 } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /schema/ }
+      end
+      context 'when the schema property is an empty string' do
+        let (:body_data ) { { 'schema' => '' } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /schema/ }
+      end
+    end
+    context 'when body is a web form' do
+      let(:body_data) { form_body_data }
+      [ 'application/x-www-form-urlencoded', 'multipart/form-data' ].each do |mtype|
+        context "when media type is #{mtype}" do
+          let(:media_type) { mtype }
+          context 'when a formParameters property is not provided' do
+            before { body_data.delete 'formParameters' }
+            it { expect { subject }.to raise_error Raml::RequiredPropertyMissing, /formParameters/ }
+          end
+          context 'when a formParameters property is provided' do
+            context 'when a formParameters property is valid' do
+              it { expect { subject }.to_not raise_error }
+              it 'stores all as Raml::Parameter::FormParameter instances' do
+                expect( subject.form_parameters.values ).to all( be_a Raml::Parameter::FormParameter )
+                subject.form_parameters.keys.should contain_exactly('param')
+              end
+            end
+            context 'when the formParameters property is not a map' do
+              before { body_data['formParameters'] = 1 }
+              it { expect { subject }.to raise_error Raml::InvalidProperty, /formParameters/ }
+            end
+            context 'when the formParameters property is not a map with non-string keys' do
+              before { body_data['formParameters'] = { 1 => {}} }
+              it { expect { subject }.to raise_error Raml::InvalidProperty, /formParameters/ }
+            end
+            context 'when the formParameters property is not a map with non-string keys' do
+              before { body_data['formParameters'] = { '1' => 'x'} }
+              it { expect { subject }.to raise_error Raml::InvalidProperty, /formParameters/ }
+            end
+          end
+          
+          context 'when a schema property is not provided' do
+            it { expect { subject }.to_not raise_error }
+          end
+          context 'when a schema property is provided' do
+            let(:body_data) {
+              YAML.load %q(
+                schema: |
+                  {
+                    "$schema": "http://json-schema.org/draft-03/schema#",
+                    "properties": {
+                        "input": {
+                            "required": false,
+                            "type": "string"
+                        }
+                    },
+                    "required": false,
+                    "type": "object"
+                  }
+                formParameters:
+                  param:
+                    type: string
+              )
+            }
+            it { expect { subject }.to raise_error Raml::InvalidProperty, /schema/ }
+          end
+        end
+      end      
+    end
+  end
+  
+  describe '#form_parameters' do
+    context 'when body is not a web form' do
+      it 'returns no form parameters' do
+        subject.form_parameters { should be_empty }
+      end
+    end
+    context 'when body is a web form' do
+      let(:body_data) { form_body_data }
+      it 'returns form parameters' do
+        subject.form_parameters { should_not be_empty }
+        expect( subject.form_parameters.values ).to all( be_a Raml::Parameter::FormParameter )
+      end
+    end
+  end
+  
+  describe '#web_form?' do
+    context 'when body isnt a web form' do
+      it { should_not be_web_form }
+    end
+    context 'when body is a web form' do
+      let(:body_data) { form_body_data }
+      [ 'application/x-www-form-urlencoded', 'multipart/form-data' ].each do |mtype|
+        context "when media type is #{mtype}" do
+          let(:media_type) { mtype }
+          it { should be_web_form }
+        end
+      end
+    end
+  end
+
+  describe '#merge' do
+    context 'when body and mixin have different media types' do
+      let(:body ) { Raml::Body.new 'foo/bar', {}, root }
+      let(:mixin) { Raml::Body.new 'foo/boo', {}, root }
+      it { expect { body.merge mixin }.to raise_error Raml::MergeError }
+    end
+    context 'when body and mixin have the same media type' do
+      let(:body ) { Raml::Body.new 'foo/bar', body_data , root }
+      let(:mixin) { Raml::Body.new 'foo/bar', mixin_data, root }
+
+      context 'when the body to merge in has a property set' do
+        context 'when the body to merge into does not have the property set' do
+          let(:body_data) { {} }
+          context 'example property' do
+            let(:mixin_data) { {'example' => 'body example'} }
+            it 'merges in the property' do
+              body.merge(mixin).example.should eq mixin.example
+            end
+          end
+          context 'schema property' do
+            let(:mixin_data) { {'schema' => 'mixin schema'} }
+            it 'merges in the property' do
+              body.merge(mixin).schema.should be_a Raml::Schema
+              body.schema.should eq mixin.schema
+            end
+          end
+          context 'formParameters properties' do
+            let(:mixin_data) { { 
+              'formParameters' => {
+                'param1' => {'description' => 'foo'}, 
+                'param2' => {'description' => 'bar'}
+              }
+            } }
+            it 'adds the form parameters to the body' do
+               body.merge(mixin).form_parameters.keys.should contain_exactly('param1', 'param2')
+            end
+          end
+        end
+        context 'when the body to merge into has the property set' do
+          context 'example property' do
+            let(:body_data ) { {'example' => 'body example'}  }
+            let(:mixin_data) { {'example' => 'mixin example'} }
+            it 'overrides the property' do
+              body.merge(mixin).example.should eq 'mixin example'
+            end
+          end
+          context 'schema property' do
+            let(:body_data ) { {'schema' => 'body schema' } }
+            let(:mixin_data) { {'schema' => 'mixin schema'} }
+            it 'overrides the property' do
+              body.merge(mixin).schema.value.should eq 'mixin schema'
+            end
+          end
+          context 'formParameters properties' do
+            let(:body_data) { { 
+              'formParameters' => {
+                'param1' => {'description' => 'foo'}, 
+                'param2' => {'description' => 'bar'}
+              }
+            } }
+            context 'when the merged in body form parameters are different from the form parametes of the body merged into' do
+              let(:mixin_data) { { 
+                'formParameters' => {
+                  'param3' => {'description' => 'foo2'}, 
+                  'param4' => {'description' => 'bar2'}
+                }
+              } }
+              it 'adds the form parameters to the body' do
+                 body.merge(mixin).form_parameters.keys.should contain_exactly('param1', 'param2', 'param3', 'param4')
+              end
+            end
+            context 'when the merged in body form parameters overlap with the form parametes of the body merged into' do
+              let(:mixin_data) { { 
+                'formParameters' => {
+                  'param2' => {'description' => 'bar3', 'displayName' => 'Param 3'}, 
+                  'param3' => {'description' => 'foo2'}, 
+                  'param4' => {'description' => 'bar2'}
+                }
+              } }
+              it 'merges the matching orm parameters and adds the non-matching orm parameters to the body' do
+                 body.merge(mixin).form_parameters.keys.should contain_exactly('param1', 'param2', 'param3', 'param4')
+                 body.form_parameters['param2'].display_name.should eq mixin.form_parameters['param2'].display_name
+                 body.form_parameters['param2'].description.should  eq mixin.form_parameters['param2'].description
+              end
+            end        
+          end
+        end
+      end
+    end
+  end
+
+  describe '#document' do
+    context 'when the body is not a form body' do
+      it 'returns a String' do
+        subject.document.should be_a String
+      end
+      it 'should render the template' do
+        mock(Slim::Template).new(/templates\/body.slim\z/, is_a(Hash)).mock!.render(is_a(Raml::Node)) { '' }
+        subject.document
+      end
+    end
+    context 'when the body is a form body' do
+      let(:media_type) { 'application/x-www-form-urlencoded' }
+      let(:body_data) { form_body_data }
+      it 'returns a String' do
+        subject.document.should be_a String
+      end
+      it 'should render the template' do
+        mock(Slim::Template).new(/templates\/body.slim\z/, is_a(Hash)).mock!.render(is_a(Raml::Node)) { '' }
+        subject.document
+      end
+    end
+  end
+end

data/test/raml/documentation_spec.rb

@@ -0,0 +1,49 @@
+# encoding: UTF-8
+require_relative 'spec_helper'
+
+describe Raml::Documentation do
+  let(:root_data) { {'title' => 'x', 'baseUri' => 'http://foo.com'} }
+  let(:root) { Raml::Root.new root_data }
+
+  let(:title) { 'Request Formats' }
+  let(:content) { <<-EOS
+Credentials
+-----------
+
+All requests to Twilio's REST API require you to authenticate using [HTTP basic auth](http://en.wikipedia.org/wiki/Basic_access_authentication) to convey your identity. The username is your AccountSid (a 34 character string, starting with the letters AC). The password is your AuthToken. Your AccountSid and AuthToken are on the [Account Dashboard](http://www.twilio.com/user/account/) page.
+
+Most HTTP clients (including web-browsers) present a dialog or prompt for you to provide a username and password for HTTP basic auth. Most clients will also allow you to provide credentials in the URL itself. For example:
+
+```
+https://{AccountSid}:{AuthToken}@api.twilio.com/2010-04-01/Accounts
+```
+
+Retrieving Resources with the HTTP GET Method
+---------------------------------------------
+
+You can retrieve a representation of a resource by GETting its url. The easiest way to do this is to copy and paste a URL into your web browser's address bar.
+
+### Possible GET Response Status Codes
+
+* 200 OK: The request was successful and the response body contains the representation requested.
+* 302 FOUND: A common redirect response; you can GET the representation at the URI in the Location response header.
+* 304 NOT MODIFIED: Your client's cached version of the representation is still up to date.
+* 401 UNAUTHORIZED: The supplied credentials, if any, are not sufficient to access the resource.
+* 404 NOT FOUND: You know this one.
+* 429 TOO MANY REQUESTS: Your application is sending too many simultaneous requests.
+* 500 SERVER ERROR: We couldn't return the representation due to an internal server error.
+* 503 SERVICE UNAVAILABLE: We are temporarily unable to return the representation. Please wait for a bit and try again.
+EOS
+	}
+  subject { Raml::Documentation.new(title, {'content' => content }, root) }
+
+  describe '#document' do
+    it 'returns a String' do
+      subject.document.should be_a String
+    end
+    it 'should render the template' do
+      mock(Slim::Template).new(/templates\/documentation.slim\z/, is_a(Hash)).mock!.render(is_a(Raml::Node)) { '' }
+      subject.document
+    end
+  end
+ end

data/test/raml/header_spec.rb

@@ -0,0 +1,17 @@
+require_relative 'spec_helper'
+
+describe Raml::Header do
+  let(:root_data) { {'title' => 'x', 'baseUri' => 'http://foo.com'} }
+  let(:root) { Raml::Root.new root_data }
+  let(:name) { 'meta' }
+  let (:data) {
+    YAML.load(%q(
+      displayName: Job Metadata
+      description: Field names prefixed with x-Zencoder-job-metadata- contain user-specified metadata.
+    ))
+  }
+
+  it "should instanciate Header" do
+    Raml::Header.new(name, data, root)
+  end
+end

data/test/raml/include_spec.rb

@@ -0,0 +1,40 @@
+require_relative 'spec_helper'
+require 'ostruct'
+
+describe Raml::Parser::Include do
+  let(:include) { Raml::Parser::Include.new }
+  describe '#init_with' do
+    it 'fetches the path from the given Psych::Coder instance' do
+      include.init_with OpenStruct.new scalar: 'path_to_file'
+      include.path.should eq 'path_to_file'
+    end
+  end
+  
+  describe '#content' do
+    before { include.init_with OpenStruct.new scalar: path }
+    context 'when the path in the include directive is absolute' do
+      let(:path) { '/absolute_file_path'}
+      it 'opens and reads the file' do
+        mock(File).open(path).stub!.read { 'content' }
+        include.content('cwd').should eq 'content'
+      end
+    end
+    context 'when the path in the include directive is relative' do
+      let(:path) { 'relative_file_path'}
+      it 'opens and reads the file' do
+        mock(File).open("cwd/#{path}").stub!.read { 'content' }
+        include.content('cwd').should eq 'content'
+      end
+    end
+    [ 'yaml', 'yml', 'raml' ].each do |ext|
+      context "when include directive points to a file ending in .#{ext}" do
+        let(:path) { "/absolute_file_path.#{ext}" }
+        let(:content) { { 'a' => [1,2,3], 'b' => 4 } }
+        it 'parses the file as YAML' do
+          stub(File).open(path).stub!.read { content.to_yaml }
+          include.content('cwd').should eq content
+        end
+      end
+    end
+  end
+end

data/test/raml/method_spec.rb

@@ -0,0 +1,701 @@
+require_relative 'spec_helper'
+
+describe Raml::Method do
+  let(:name) { 'get' }
+  let(:data) {
+    YAML.load(%q(
+      description: Get a list of users
+      queryParameters:
+        page:
+          description: Specify the page that you want to retrieve
+          type: integer
+          required: true
+          example: 1
+        per_page:
+          description: Specify the amount of items that will be retrieved per page
+          type: integer
+          minimum: 10
+          maximum: 200
+          default: 30
+          example: 50
+      protocols: [ HTTP, HTTPS ]
+      responses:
+        200:
+          description: |
+            The list of popular media.
+    ))
+  }
+  let(:root_data) { {'title' => 'x', 'baseUri' => 'http://foo.com'} }
+  let(:root) { Raml::Root.new root_data }
+
+  subject { Raml::Method.new(name, data, root) }
+
+  describe '#new' do
+    it "should instanciate Method" do
+      subject
+    end
+    
+    context 'when the method is a method defined in RFC2616 or RFC5789' do
+      %w(options get head post put delete trace connect patch).each do |method|
+        context "when the method is #{method}" do
+          let(:name) { method }
+          it { expect { subject }.to_not raise_error }
+        end
+      end
+    end
+    context 'when the method is an unsupported method' do
+      %w(propfind proppatch mkcol copy move lock unlock).each do |method|
+        context "when the method is #{method}" do
+          let(:name) { method }
+          it { expect { subject }.to raise_error Raml::InvalidMethod }
+        end
+      end
+    end
+    
+    context 'when description property is not given' do
+      let(:data) { {} }
+      it { expect { subject }.to_not raise_error }
+    end
+    context 'when description property is given' do
+      context 'when the description property is not a string' do
+        let(:data) { { 'description' => 1 } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /description/ }
+      end
+      context 'when the description property is a string' do
+        let(:data) { { 'description' => 'My Description' } }
+        it { expect { subject }.to_not raise_error }
+        it 'should store the value' do
+          subject.description.should eq data['description']
+        end
+        it 'uses the description in the documentation' do
+          subject.document.should include data['description']
+        end
+      end
+    end
+    
+    context 'when the headers parameter is given' do
+      context 'when the headers property is well formed' do
+        let (:data) {
+          YAML.load(%q(
+            headers:
+              Zencoder-Api-Key:
+                displayName: ZEncoder API Key
+              x-Zencoder-job-metadata-{*}:
+                displayName: Job Metadata
+          ))
+        }
+        it { expect { subject }.to_not raise_error }
+        it 'stores all as Raml::Header instances' do
+          expect( subject.headers.values ).to all( be_a Raml::Header )
+          expect( subject.headers.keys   ).to contain_exactly('Zencoder-Api-Key','x-Zencoder-job-metadata-{*}')
+        end
+      end
+      context 'when the headers property is not a map' do
+        let(:data) { { 'headers' => 1 } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /headers/ }
+      end
+      context 'when the headers property is not a map with non-string keys' do
+        let(:data) { { 'headers' => { 1 => {}} } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /headers/ }
+      end
+      context 'when the headers property is not a map with non-string keys' do
+        let(:data) { { 'headers' => { '1' => 'x'} } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /headers/ }
+      end
+    end
+    
+    context 'when the protocols property is missing' do
+      let(:data) { { } }
+      it { expect{ subject }.to_not raise_error }
+    end
+    context 'when the protocols property is given' do
+      context 'when the protocol property is not an array' do
+        let(:data) { { 'protocols' => 'HTTP' } }
+        it { expect{ subject }.to raise_error Raml::InvalidProperty, /protocols/ }
+      end
+      context 'when the protocol property is an array but not all elements are strings' do
+        let(:data) { { 'protocols' => ['HTTP', 1] } }
+        it { expect{ subject }.to raise_error Raml::InvalidProperty, /protocols/ }
+      end
+      context 'when the protocol property is an array of strings with invalid values' do
+        let(:data) { { 'protocols' => ['HTTP', 'foo'] } }
+        it { expect{ subject }.to raise_error Raml::InvalidProperty, /protocols/ }
+      end
+      [
+        [ 'HTTP'  ],
+        [ 'HTTPS' ],
+        [ 'HTTP', 'HTTPS' ]
+      ].each do |protocols|
+        context "when the protocol property is #{protocols}" do
+          let(:data) { { 'protocols' => protocols } }
+          it { expect{ subject }.to_not raise_error }
+          it 'stores the values' do
+            subject.protocols.should eq protocols
+          end
+        end
+      end
+      context 'when the protocol property is an array of valid values in lowercase' do
+        let(:data) { { 'protocols' => ['http', 'https'] } }
+        it 'uppercases them' do
+          subject.protocols.should eq [ 'HTTP', 'HTTPS' ]
+        end
+      end
+    end
+    
+    context 'when a queryParameters property is given' do
+      context 'when the queryParameters property is well formed' do
+        let(:data) {
+          YAML.load(
+            %q(
+              description: Get a list of users
+              queryParameters:
+                page:
+                  description: Specify the page that you want to retrieve
+                  type: integer
+                  required: true
+                  example: 1
+                per_page:
+                  description: Specify the amount of items that will be retrieved per page
+                  type: integer
+                  minimum: 10
+                  maximum: 200
+                  default: 30
+                  example: 50
+            )
+          )
+        }
+        
+        it { expect { subject }.to_not raise_error }
+        it 'stores all as Raml::Parameter::UriParameter instances' do
+          expect( subject.query_parameters.values ).to all( be_a Raml::Parameter::QueryParameter )
+          subject.query_parameters.keys.should contain_exactly('page', 'per_page')
+        end
+      end
+      context 'when the queryParameters property is not a map' do
+        before { data['queryParameters'] = 1 }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /queryParameters/ }
+      end
+      context 'when the queryParameters property is not a map with non-string keys' do
+        before { data['queryParameters'] = { 1 => {}} }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /queryParameters/ }
+      end
+      context 'when the queryParameters property is not a map with non-string keys' do
+        before { data['queryParameters'] = { '1' => 'x'} }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /queryParameters/ }
+      end
+    end
+
+    context 'when a body property is given' do
+      context 'when the body property is well formed' do
+        let(:data) {
+          YAML.load(
+            %q(
+            description: Create a Job
+            body:
+              text/xml:
+                schema: job_xml_schema
+              application/json:
+                schema: json_xml_schema
+            )
+          )
+        }
+        
+        it { expect { subject }.to_not raise_error }
+        it 'stores all as Raml::Body instances' do
+          expect( subject.bodies.values ).to all( be_a Raml::Body )
+          subject.bodies.keys.should contain_exactly('text/xml', 'application/json')
+        end
+      end
+      context 'when the body property is not a map' do
+        before { data['body'] = 1 }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /body/ }
+      end
+      context 'when the body property is a map with non-string keys' do
+        before { data['body'] = { 1 => {}} }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /body/ }
+      end
+      context 'when the body property is a map with non-map values' do
+        before { data['body'] = { 'text/xml' => 1 } }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /body/ }
+      end
+    end
+    
+    context 'when a responses property is given' do
+      context 'when the responses property is well formed' do
+        let(:data) {
+          YAML.load(
+            %q(
+              responses:
+                200:
+                  body:
+                    application/json:
+                      example: !include examples/instagram-v1-media-popular-example.json
+                503:
+                  description: The service is currently unavailable.
+            )
+          )
+        }
+        
+        it { expect { subject }.to_not raise_error }
+        it 'stores all as Raml::Response instances' do
+          expect( subject.responses.values ).to all( be_a Raml::Response )
+          subject.responses.keys.should contain_exactly(200, 503)
+        end
+      end
+      context 'when the responses property is not a map' do
+        before { data['responses'] = 1 }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /responses/ }
+      end
+      context 'when the responses property is not a map with string integer keys' do
+        before { data['responses'] = { '200' => {}} }
+        it { expect { subject }.not_to raise_error }
+      end
+      context 'when the responses property is not a map with non-string keys' do
+        before { data['responses'] = { 200 => 'x'} }
+        it { expect { subject }.to raise_error Raml::InvalidProperty, /responses/ }
+      end
+    end
+
+    context 'when an is property is given' do
+     let(:root) { 
+        Raml::Root.new 'title' => 'x', 'baseUri' => 'http://foo.com',  'traits' => [
+          { 'secured'     => {} },
+          { 'paged'       => {} },
+          { 'rateLimited' => {} }
+        ]
+      }
+      context 'when the property is valid' do
+        context 'when the property is an array of trait references' do
+          let(:data) { { 'is' => [ 'secured', 'paged' ] } }
+          it { expect { subject }.to_not raise_error }
+          it 'should store the trait references' do
+            subject.traits.should all( be_a Raml::TraitReference )
+            subject.traits.map(&:name).should contain_exactly('secured', 'paged')
+          end
+        end
+        context 'when the property is an array of trait references with parameters' do
+          let(:data) { { 
+            'is' => [ 
+              {'secured' => {'tokenName' => 'access_token'}}, 
+              {'paged'   => {'maxPages'  => 10            }} 
+            ] 
+          } }
+          it { expect { subject }.to_not raise_error }
+          it 'should store the trait references' do
+            subject.traits.should all( be_a Raml::TraitReference )
+            subject.traits.map(&:name).should contain_exactly('secured', 'paged')
+          end
+        end
+        context 'when the property is an array of trait definitions' do
+          let(:data) { { 
+            'is' => [ 
+              {'queryParameters' => {'tokenName' => {'description'=>'foo'}}}, 
+              {'queryParameters' => {'numPages'  => {'description'=>'bar'}}}
+            ] 
+          } }
+          it { expect { subject }.to_not raise_error }
+          it 'should store the traits' do
+            subject.traits.should all( be_a Raml::Trait )
+            subject.traits[0].value.should eq ({'queryParameters' => {'tokenName' => {'description'=>'foo'}}})
+            subject.traits[1].value.should eq ({'queryParameters' => {'numPages'  => {'description'=>'bar'}}})
+          end
+        end
+        context 'when the property is an array of mixed trait refrences, trait refrences with parameters, and trait definitions' do
+          let(:data) { { 
+            'is' => [ 
+              {'secured' => {'tokenName' => 'access_token'}}, 
+              {'queryParameters' => {'numPages'  => {'description'=>'bar'}}},
+              'rateLimited'
+            ] 
+          } }
+          it { expect { subject }.to_not raise_error }
+          it 'should store the traits' do
+            subject.traits.select {|t| t.is_a? Raml::TraitReference }.map(&:name).should contain_exactly('secured', 'rateLimited')
+            subject.traits.select {|t| t.is_a? Raml::Trait}[0].value.should eq ({'queryParameters' => {'numPages'  => {'description'=>'bar'}}})
+          end
+        end
+      end
+      context 'when the property is invalid' do
+        context 'when the property is not an array' do
+          let(:data) { { 'is' => 1 } }
+          it { expect { subject }.to raise_error Raml::InvalidProperty, /is/ }
+        end
+        context 'when the property is an array with elements other than a string or map' do
+          let(:data) { { 'is' => [1] } }
+          it { expect { subject }.to raise_error Raml::InvalidProperty, /is/ }
+        end
+        context 'when the property is an array an element that appears to be a trait name with parameters, but the params are not a map' do
+          let(:data) { { 'is' => [ { 'secured' => 1 } ] } }
+          it { expect { subject }.to raise_error Raml::InvalidProperty, /is/ }
+        end
+      end
+    end
+
+    context 'when the syntax tree contains optional properties' do
+      let(:data) {
+        YAML.load(%q(
+          description: Get a list of users
+          queryParameters:
+            page?:
+              description: Specify the page that you want to retrieve
+              type: integer
+              required: true
+              example: 1
+          protocols: [ HTTP, HTTPS ]
+          responses:
+            200:
+              description: |
+                The list of popular media.
+        ))
+      }
+      it { expect {subject }.to raise_error Raml::InvalidProperty, /Optional properties/ }
+    end
+  end
+
+  describe '#merge' do
+    let(:method) { Raml::Method.new 'get'       , method_data, root }
+    let(:trait ) { Raml::Trait.new( 'trait_name', trait_data , root).instantiate({}) }
+    context 'when the trait has a property set' do
+      context 'when the method does not have that property set' do
+        let(:method_data) { {} }
+        context 'description property' do
+          let(:trait_data) { {description: 'trait description'} }
+          it 'sets the property in the method' do
+            method.merge(trait).description.should eq trait.description
+          end
+        end
+        context 'protocols property' do
+          let(:trait_data) { {protocols: ['HTTPS']} }
+          it 'sets the property in the method' do
+            method.merge(trait).protocols.should eq trait.protocols
+          end
+        end
+        context 'headers properties' do
+          let(:trait_data) { { 
+            'headers' => {
+              'header1' => {'description' => 'foo'}, 
+              'header2' => {'description' => 'bar'}
+            }
+          } }
+          it 'adds the headers to the method' do
+             method.merge(trait).headers.keys.should contain_exactly('header1', 'header2')
+          end
+        end
+        context 'queryParameters properties' do
+          let(:trait_data) { { 
+            'queryParameters' => {
+              'param1' => {'description' => 'foo'}, 
+              'param2' => {'description' => 'bar'}
+            }
+          } }
+          it 'adds the headers to the method' do
+             method.merge(trait).query_parameters.keys.should contain_exactly('param1', 'param2')
+          end
+        end
+        context 'body property' do
+          let(:trait_data) { { 
+            'body' => {
+              'text/mime1' => {'schema' => 'foo'}, 
+              'text/mime2' => {'schema' => 'bar'}
+            }
+          } }
+          it 'adds the body media types to the method' do
+             method.merge(trait).bodies.keys.should contain_exactly('text/mime1', 'text/mime2')
+          end
+        end
+        context 'responses property' do
+          let(:trait_data) { { 
+            'responses' => {
+              200 => {'description' => 'foo'}, 
+              404 => {'description' => 'bar'}
+            }
+          } }
+          it 'adds the responses to the method' do
+             method.merge(trait).responses.keys.should contain_exactly(200, 404)
+          end
+        end
+        context 'usage property' do
+          let(:trait_data) { { 'usage' => 'trait usage' } }
+          it 'does not add the usage property to the method' do
+             method.merge(trait)
+             expect { method.usage }.to raise_error NoMethodError
+          end
+        end
+      end
+      context 'when the method has that property set' do
+        context 'description property' do
+          let(:method_data) { {description: 'method description'} }
+          let(:trait_data ) { {description: 'trait description' } }
+          it 'overwrites the method property' do
+            method.merge(trait).description.should eq 'trait description'
+          end
+        end
+        context 'protocols property' do
+          let(:method_data) { {protocols: ['HTTP' ]} }
+          let(:trait_data ) { {protocols: ['HTTPS']} }
+          it 'overwrites the method property' do
+            method.merge(trait).protocols.should eq ['HTTPS']
+          end
+        end
+        context 'headers properties' do
+          let(:method_data) { { 
+            'headers' => {
+              'header1' => {'description' => 'foo'}, 
+              'header2' => {'description' => 'bar'}
+            }
+          } }
+          context 'when the trait headers are different from the method headers' do
+            let(:trait_data) { { 
+              'headers' => {
+                'header3' => {'description' => 'foo2'}, 
+                'header4' => {'description' => 'bar2'}
+              }
+            } }
+            it 'adds the headers to the method' do
+               method.merge(trait).headers.keys.should contain_exactly('header1', 'header2', 'header3', 'header4')
+            end
+          end
+          context 'when the trait headers overlap the the method headers' do
+            let(:trait_data) { { 
+              'headers' => {
+                'header2' => {'displayName' => 'Header 3'}, 
+                'header3' => {'description' => 'foo2'}, 
+                'header4' => {'description' => 'bar2'}
+              }
+            } }
+            it 'merges the matching headers and adds the non-matching headers to the method' do
+               method.merge(trait).headers.keys.should contain_exactly('header1', 'header2', 'header3', 'header4')
+               method.headers['header2'].display_name.should eq trait.headers['header2'].display_name
+            end
+          end        
+        end
+        context 'queryParameters properties' do
+          let(:method_data) { { 
+            'queryParameters' => {
+              'param1' => {'description' => 'foo'}, 
+              'param2' => {'description' => 'bar'}
+            }
+          } }
+          context 'when the trait query parameters are different from the method headers' do
+            let(:trait_data) { { 
+              'queryParameters' => {
+                'param3' => {'description' => 'foo2'}, 
+                'param4' => {'description' => 'bar2'}
+              }
+            } }
+            it 'adds the query parameters to the method' do
+               method.merge(trait).query_parameters.keys.should contain_exactly('param1', 'param2', 'param3', 'param4')
+            end
+          end
+          context 'when the trait query parameters overlap the the method query parameters' do
+            let(:trait_data) { { 
+              'queryParameters' => {
+                'param2' => {'displayName' => 'Param 3'}, 
+                'param3' => {'description' => 'foo2'}, 
+                'param4' => {'description' => 'bar2'}
+              }
+            } }
+            it 'merges the matching headers and adds the non-matching headers to the method' do
+               method.merge(trait).query_parameters.keys.should contain_exactly('param1', 'param2', 'param3', 'param4')
+               method.query_parameters['param2'].display_name.should eq trait.query_parameters['param2'].display_name
+            end
+          end         
+        end
+        context 'body property' do
+          let(:method_data) { { 
+            'body' => {
+              'text/mime1' => {'schema' => 'foo'}, 
+              'text/mime2' => {'schema' => 'bar'}
+            }
+          } }
+          context 'when the trait query parameters are different from the method headers' do
+            let(:trait_data) { { 
+              'body' => {
+                'text/mime3' => {'schema' => 'foo2'}, 
+                'text/mime4' => {'schema' => 'bar2'}
+              }
+            } }
+            it 'adds the body media types to the method' do
+               method.merge(trait).bodies.keys.should contain_exactly('text/mime1', 'text/mime2', 'text/mime3', 'text/mime4')
+            end
+          end
+          context 'when the trait query parameters overlap the the method query parameters' do
+            let(:trait_data) { { 
+              'body' => {
+                'text/mime2' => {'example' => 'Example 2'}, 
+                'text/mime3' => {'schema'  => 'foo2'}, 
+                'text/mime4' => {'schema'  => 'bar2'}
+              }
+            } }
+            it 'merges the matching media types and adds the non-matching media types to the method' do
+               method.merge(trait).bodies.keys.should contain_exactly('text/mime1', 'text/mime2', 'text/mime3', 'text/mime4')
+               method.bodies['text/mime2'].example.should eq trait.bodies['text/mime2'].example
+            end
+          end  
+        end
+        context 'responses property' do
+          let(:method_data) { { 
+            'responses' => {
+              200 => {'description' => 'foo', 'body' => { 'text/mime1' => {'schema' => 'schema1'} } }, 
+              404 => {'description' => 'bar'}
+            }
+          } }
+          context 'when the trait response status codes are different from the method responses status codes' do
+            let(:trait_data) { { 
+              'responses' => {
+                201 => {'description' => 'foo2'}, 
+                403 => {'description' => 'bar2'}
+              }
+            } }
+            it 'adds the body media types to the method' do
+               method.merge(trait).responses.keys.should contain_exactly(200, 404, 201, 403)
+            end
+          end
+          context 'when the trait query parameters overlap the the method query parameters' do
+            let(:trait_data) { { 
+              'responses' => {
+                200 => {'description' => 'foo', 'body' => { 'text/mime2' => {'schema' => 'schema2'} } }, 
+                201 => {'description' => 'foo2'}, 
+                403 => {'description' => 'bar2'}
+              }
+            } }
+            it 'merges the matching media types and adds the non-matching media types to the method' do
+               method.merge(trait).responses.keys.should contain_exactly(200, 404, 201, 403)
+               method.responses[200].bodies.keys.should contain_exactly('text/mime1', 'text/mime2')
+            end
+          end  
+        end
+      end
+    end
+  end
+
+  describe '#apply_traits' do
+    let(:root_data) { {
+      'title'   => 'x', 
+      'baseUri' => 'http://foo.com',
+      '/users'  => {
+        '/comments' => {
+          'is'  => resource_trait_data,
+          'get' => method_data
+        }
+      }
+    } }
+    let(:method) { root.resources['/users'].resources['/comments'].methods['get'] }
+    before {  method.apply_traits }
+    describe 'order application' do
+      context 'when given no resource traits' do
+        let(:resource_trait_data) { [] }
+        context 'when method has a trait' do
+          let(:method_data) { { 'is' => [ { 'description' => 'trait description' } ] } }
+          it 'applies the method trait' do
+            method.description.should eq 'trait description'
+          end
+        end
+        context 'when the method has multiple traits' do
+          let(:method_data) { { 
+            'is' => [ 
+              { 
+                'description' => 'trait description',
+                'headers'     => { 'header1' => { 'description' => 'header1' } }
+              },
+              {
+                'description' => 'trait description 2',
+                'headers'     => { 'header2' => { 'description' => 'header2' } }
+              } 
+            ]
+          } }
+          it 'applies them in order of precedence, right to left' do
+            method.description.should eq 'trait description 2'
+            method.headers.keys.should contain_exactly('header1', 'header2')
+          end
+        end
+      end
+      context 'when given resource traits' do
+        let(:resource_trait_data) { [ { 'description' => 'resource trait description' } ] }
+        context 'when the method has no traits' do
+          let(:method_data) { {} }
+          it 'applies the resource trait' do
+            method.description.should eq 'resource trait description'
+          end
+        end
+        context 'when the method has traits' do
+          let(:resource_trait_data) {
+            [ 
+              { 
+                'description' => 'trait4 description',
+                'headers'     => { 
+                  'header3' => { 'description' => 'trait4' },
+                  'header4' => { 'description' => 'trait4' } 
+                }
+              },
+              {
+                'description' => 'trait3 description',
+                'headers'     => { 
+                  'header2' => { 'description' => 'trait3' },
+                  'header3' => { 'description' => 'trait3' }
+                }
+              } 
+            ]
+          }
+          let(:method_data) { { 
+            'description' => 'method description',
+            'is' => [ 
+              { 
+                'description' => 'trait2 description',
+                'headers'     => { 
+                  'header1' => { 'description' => 'trait2' },
+                  'header2' => { 'description' => 'trait2' }
+                }
+              },
+              {
+                'description' => 'trait1 description',
+                'headers'     => { 
+                  'header1' => { 'description' => 'trait1' }
+                }
+              } 
+            ]
+          } }
+          it 'applies method traits first in reverse order, then resource traits in reverse order' do
+            method.description.should eq 'method description'
+            method.headers.keys.should contain_exactly('header1','header2', 'header3', 'header4')
+            method.headers['header1'].description.should eq 'trait1'
+            method.headers['header2'].description.should eq 'trait2'
+            method.headers['header3'].description.should eq 'trait3'
+            method.headers['header4'].description.should eq 'trait4'
+          end
+        end
+      end
+    end
+    describe 'reserved parameters' do
+      let(:resource_trait_data) { [] }
+      context 'resourcePath' do
+        let(:method_data) { { 'is' => [ { 'description' => 'trait <<resourcePath>>' } ] } }
+        it 'instances traits with the reserved parameter' do
+          method.description.should eq 'trait /users/comments'
+        end
+      end
+      context 'resourcePathName' do
+        let(:method_data) { { 'is' => [ { 'description' => 'trait <<resourcePathName>>' } ] } }
+        it 'instances traits with the reserved parameter' do
+          method.description.should eq 'trait comments'
+        end
+      end
+      context 'methodName' do
+        let(:method_data) { { 'is' => [ { 'description' => 'trait <<methodName>>' } ] } }
+        it 'instances traits with the reserved parameter' do
+          method.description.should eq 'trait get'
+        end
+      end
+    end
+  end
+
+  describe '#document' do
+    it 'returns a String' do
+      subject.document.should be_a String
+    end
+    it 'should render the template' do
+      mock(Slim::Template).new(/templates\/method.slim\z/, is_a(Hash)).mock!.render(is_a(Raml::Node)) { '' }
+      subject.document
+    end
+  end
+end