soaspec 0.2.33 → 0.3.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (86) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +15 -15
  3. data/.gitlab-ci.yml +62 -62
  4. data/.rspec +3 -3
  5. data/.rubocop.yml +2 -2
  6. data/CODE_OF_CONDUCT.md +74 -74
  7. data/ChangeLog +643 -632
  8. data/Dockerfile +7 -7
  9. data/Gemfile +8 -8
  10. data/LICENSE.txt +21 -21
  11. data/README.md +253 -231
  12. data/Rakefile +52 -52
  13. data/Todo.md +16 -16
  14. data/exe/soaspec +140 -138
  15. data/exe/xml_to_yaml_file +43 -43
  16. data/lib/soaspec.rb +118 -106
  17. data/lib/soaspec/baseline.rb +82 -22
  18. data/lib/soaspec/core_ext/hash.rb +44 -44
  19. data/lib/soaspec/cucumber/generic_steps.rb +94 -94
  20. data/lib/soaspec/demo.rb +6 -6
  21. data/lib/soaspec/errors.rb +24 -24
  22. data/lib/soaspec/exchange/exchange.rb +131 -129
  23. data/lib/soaspec/exchange/exchange_extractor.rb +105 -90
  24. data/lib/soaspec/exchange/exchange_properties.rb +28 -28
  25. data/lib/soaspec/exchange/exchange_repeater.rb +21 -21
  26. data/lib/soaspec/exchange/request_builder.rb +108 -70
  27. data/lib/soaspec/exchange/variable_storer.rb +24 -24
  28. data/lib/soaspec/exchange_handlers/exchange_handler.rb +98 -98
  29. data/lib/soaspec/exchange_handlers/exchange_handler_defaults.rb +61 -61
  30. data/lib/soaspec/exchange_handlers/handler_accessors.rb +132 -132
  31. data/lib/soaspec/exchange_handlers/request/rest_request.rb +77 -59
  32. data/lib/soaspec/exchange_handlers/request/soap_request.rb +41 -41
  33. data/lib/soaspec/exchange_handlers/response_extractor.rb +84 -84
  34. data/lib/soaspec/exchange_handlers/rest_exchanger_factory.rb +111 -111
  35. data/lib/soaspec/exchange_handlers/rest_handler.rb +307 -307
  36. data/lib/soaspec/exchange_handlers/rest_methods.rb +65 -65
  37. data/lib/soaspec/exchange_handlers/rest_parameters.rb +112 -112
  38. data/lib/soaspec/exchange_handlers/rest_parameters_defaults.rb +42 -42
  39. data/lib/soaspec/exchange_handlers/soap_handler.rb +241 -241
  40. data/lib/soaspec/exe_helpers.rb +94 -94
  41. data/lib/soaspec/generate_server.rb +48 -48
  42. data/lib/soaspec/generator/.rspec.erb +5 -5
  43. data/lib/soaspec/generator/.travis.yml.erb +5 -5
  44. data/lib/soaspec/generator/Gemfile.erb +8 -8
  45. data/lib/soaspec/generator/README.md.erb +29 -29
  46. data/lib/soaspec/generator/Rakefile.erb +20 -19
  47. data/lib/soaspec/generator/config/data/default.yml.erb +2 -2
  48. data/lib/soaspec/generator/css/bootstrap.css +6833 -6833
  49. data/lib/soaspec/generator/features/support/env.rb.erb +3 -3
  50. data/lib/soaspec/generator/generate_exchange.html.erb +47 -47
  51. data/lib/soaspec/generator/lib/blz_service.rb.erb +26 -26
  52. data/lib/soaspec/generator/lib/dynamic_class_content.rb.erb +12 -12
  53. data/lib/soaspec/generator/lib/new_rest_service.rb.erb +56 -56
  54. data/lib/soaspec/generator/lib/new_soap_service.rb.erb +29 -29
  55. data/lib/soaspec/generator/lib/package_service.rb.erb +2 -2
  56. data/lib/soaspec/generator/lib/shared_example.rb.erb +8 -8
  57. data/lib/soaspec/generator/spec/dynamic_soap_spec.rb.erb +12 -12
  58. data/lib/soaspec/generator/spec/rest_spec.rb.erb +9 -9
  59. data/lib/soaspec/generator/spec/soap_spec.rb.erb +51 -51
  60. data/lib/soaspec/generator/spec/spec_helper.rb.erb +23 -23
  61. data/lib/soaspec/generator/template/soap_template.xml +6 -6
  62. data/lib/soaspec/indifferent_hash.rb +9 -9
  63. data/lib/soaspec/interpreter.rb +70 -70
  64. data/lib/soaspec/matchers.rb +136 -140
  65. data/lib/soaspec/o_auth2.rb +142 -142
  66. data/lib/soaspec/soaspec_shared_examples.rb +26 -26
  67. data/lib/soaspec/spec_logger.rb +143 -143
  68. data/lib/soaspec/template_reader.rb +30 -30
  69. data/lib/soaspec/test_server/bank.wsdl +90 -90
  70. data/lib/soaspec/test_server/get_bank.rb +166 -166
  71. data/lib/soaspec/test_server/id_manager.rb +41 -41
  72. data/lib/soaspec/test_server/invoices.rb +29 -29
  73. data/lib/soaspec/test_server/namespace.xml +14 -14
  74. data/lib/soaspec/test_server/note.xml +5 -5
  75. data/lib/soaspec/test_server/puppy_service.rb +21 -21
  76. data/lib/soaspec/test_server/test_attribute.rb +14 -14
  77. data/lib/soaspec/test_server/test_namespace.rb +14 -14
  78. data/lib/soaspec/version.rb +6 -6
  79. data/lib/soaspec/virtual_server.rb +193 -190
  80. data/lib/soaspec/wait.rb +43 -43
  81. data/lib/soaspec/wsdl_generator.rb +215 -215
  82. data/soaspec.gemspec +58 -58
  83. data/test.wsdl +116 -116
  84. data/test.xml +10 -10
  85. data/test_wsdl.rb +43 -43
  86. metadata +3 -3
data/Dockerfile CHANGED
@@ -1,8 +1,8 @@
1
- FROM ruby:2.6
2
- MAINTAINER Samuel Garratt
3
- LABEL url="https://gitlab.com/samuel-garratt/soaspec/blob/master/Dockerfile"
4
- # Simple Dockerfile with gems preinstalled
5
- RUN gem install bundler rake soaspec
6
- ENV LANG=en_US.UTF-8
7
- ENV LANGUAGE=en_US.UTF-8
1
+ FROM ruby:2.6
2
+ MAINTAINER Samuel Garratt
3
+ LABEL url="https://gitlab.com/samuel-garratt/soaspec/blob/master/Dockerfile"
4
+ # Simple Dockerfile with gems preinstalled
5
+ RUN gem install bundler rake soaspec
6
+ ENV LANG=en_US.UTF-8
7
+ ENV LANGUAGE=en_US.UTF-8
8
8
  ENV LC_ALL=en_US.UTF-8
data/Gemfile CHANGED
@@ -1,8 +1,8 @@
1
- # frozen_string_literal: true
2
-
3
- source 'https://rubygems.org'
4
-
5
- git_source(:gitlab) { |_repo_name| 'https://gitlab.com/samuel-garratt/soaspec' }
6
-
7
- # Specify your gem's dependencies in soaspec.gemspec
8
- gemspec
1
+ # frozen_string_literal: true
2
+
3
+ source 'https://rubygems.org'
4
+
5
+ git_source(:gitlab) { |_repo_name| 'https://gitlab.com/samuel-garratt/soaspec' }
6
+
7
+ # Specify your gem's dependencies in soaspec.gemspec
8
+ gemspec
@@ -1,21 +1,21 @@
1
- The MIT License (MIT)
2
-
3
- Copyright (c) 2018 Samuel Garratt
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in
13
- all copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2018 Samuel Garratt
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md CHANGED
@@ -1,231 +1,253 @@
1
- # Soaspec
2
-
3
- This gem helps to represent multiple API tests against a backend briefly, concisely and clearly.
4
-
5
- ![Soaspec example](images/basic_demo.gif)
6
- > Example showing how a REST 'get' call can be made and it's response extracted.
7
-
8
- [![Build Status](https://gitlab.com/samuel-garratt/soaspec/badges/master/build.svg)](https://gitlab.com/samuel-garratt/soaspec/pipelines)
9
- [![Coverage](https://gitlab.com/samuel-garratt/soaspec/badges/master/coverage.svg)](https://samuel-garratt.gitlab.io/soaspec/coverage)
10
-
11
- It is essentially a wrapper around the Savon and RestClient gems, adding useful functionality including
12
-
13
- * Creating multiple API calls from the same base configuration through the use of an `ExchangeHandler` class
14
- * Extracting values from response body's through either `XPath` or `JSONPath`
15
- * Building up a custom RSpec `success scenario` shared example to reuse common tests on an API
16
- * Methods simplifying setting and extracting values from a `Request/Response` pair (`Exchange`)
17
- * Waiting for a particular response from an API by polling it
18
- * Representing paths to values from a response with business-meaningful method names
19
- * Generating initial code for testing an API with `soaspec new`
20
- * Accessing and utilising `oauth2` access tokens
21
- * Hosting a `virtual_server` that simulates REST & SOAP responses from an API
22
-
23
- ## Installation
24
-
25
- Add this line to your application's Gemfile:
26
-
27
- ```ruby
28
- gem 'soaspec'
29
- ```
30
-
31
- And then execute:
32
-
33
- $ bundle
34
-
35
- Or install it yourself as:
36
-
37
- $ gem install soaspec
38
-
39
- [Things to be done](Todo.md)
40
-
41
- ## Getting Started
42
-
43
- To create a new test suite using this you can use the `soaspec` binary.
44
-
45
- Example:
46
-
47
- ```
48
- mkdir 'api_test'
49
- cd 'api_test'
50
- soaspec new [rest/soap]
51
- bundle install
52
- ```
53
-
54
- Then you can run the tests with:
55
-
56
- ```
57
- rake spec
58
- ```
59
-
60
- You can also use `soaspec generate` to generate a set of tests from a WSDL. This is still in trial period and will be finished probably after Savon 3 is more stable.
61
-
62
- ## Usage
63
-
64
- * SOAP - this uses Savon behind the scenes. Some defaults are overridden. Please see 'soap_handler.rb'-'default_options' method
65
- for such defaults. When describing an API override this in 'savon_options' method
66
- * REST - this uses the resource class from the Rest-Client gem behind the scenes.
67
-
68
- See [spec](spec) and [features](features) for example of usage.
69
-
70
- ### ExchangeHandler
71
-
72
- To start with, create a class inheriting from a ‘Handler’ class for each web service that needs testing.
73
- In this class you define the common parameters used for testing it.
74
-
75
- For example:
76
-
77
- ```ruby
78
- # Classes are set up through inheriting from either `Soaspec::RestHandler` or `Soaspec::SoapHandler`
79
- class PuppyService < Soaspec::RestHandler
80
- # Set default headers for all `Exchanges` using this class
81
- headers accept: 'application/json', content_type: 'application/json'
82
-
83
- # URL for which all requests using this class will start with
84
- base_url 'http://petstore.swagger.io/v2/pet'
85
-
86
- # Accessing parts of a response
87
-
88
- # Define a method 'id' that can be obtained with either XPATH '//id' or JSONPath '$..id'
89
- element :id, :id
90
- # Define method to obtain a category id through JSON Path
91
- element :category_id, '$..category.id'
92
- end
93
- ```
94
-
95
- > You can easily create a exchange handler with the `soaspec add` command. This will also add comments explaining common methods that can be used
96
-
97
- ### Exchange
98
-
99
- After creating the `ExchangeHandler`, you reference this class in creating `Exchange`s (objects that each represent a request / response pair).
100
- Upon initialization of the Exchange object (or later on through setters), parameters specific to this request are set.
101
- Most getters of the `Exchange` are on the response & will implicitly trigger the API request to be made.
102
- Once this request has been made, all following accessors of the response will just use the response of the previous request made.
103
-
104
- For example, to create a http post using the above `ExchangeHandler` and get parts of it's response.
105
- ```ruby
106
- # Create a new Exchange that will post to 'http://petstore.swagger.io/v2/pet' with JSON { "status": "sold" }
107
- # The 'body' key will convert it's value from a Hash to JSON
108
- exchange = PuppyService.post(body: { status: 'sold' })
109
-
110
- # This will trigger the request to be made & return the response, in this case a RestClient::Response object
111
- response = exchange.response
112
- # This will reuse the response already received return a value at JSON path $..category.id, throwing an exception if not found
113
- exchange.category_id
114
- # This will do the same but using path directly in code
115
- exchange['$..category.id']
116
- # Get the HTTP status code of the response
117
- exchange.status_code
118
- ```
119
-
120
- See [Request Body Parameters](https://gitlab.com/samuel-garratt/soaspec/wikis/RequestBodyParameters) for more details on setting a request body.
121
- See [Creating an Exchange](https://gitlab.com/samuel-garratt/soaspec/wikis/CreatingExchange) for details on how to create an Exchange.
122
-
123
- ### Virtual Server
124
-
125
- Soaspec includes a virtual server that returns REST and SOAP responses that can be used when learning or experimenting with API testing.
126
- The gem itself uses this to test it's own functionality.
127
-
128
- To start the server, after installing the gem, type
129
-
130
- ```
131
- soaspec virtual_server [port_num]
132
- ```
133
-
134
- By default it runs on port 4999. This will be used if `port_num` is empty.
135
-
136
- You can look at the documentation for the web services provided at the rool url (e.g `localhost:4999`).
137
-
138
- ### RSpec
139
-
140
- For example:
141
-
142
- ```ruby
143
- context PuppyService.new('Order Puppies') do
144
- describe post(:create_pet, body: { status: 'sold' }) do # Post with status as sold in request
145
- its(['status']) { is_expected.to eq 'sold' } # Check responses status is sold
146
- end
147
- end
148
- ```
149
-
150
- #### Tips
151
-
152
- If you find having a large backtrace on errors or RSpec shared examples such as 'success scenarios' this can shorten the
153
- backtrace.
154
-
155
- RSpec.configure do |config|
156
-
157
- config.backtrace_exclusion_patterns = [
158
- /rspec/
159
- ]
160
- end
161
-
162
- ### Cucumber
163
-
164
- If you're using `Cucumber` for testing a single API call then I would
165
- recommend the following
166
-
167
- In the `Given` (or background) specify the `Exchange` object.
168
- Either store this as an instance variable (e.g `@exchange`) or use the global `Soaspec.last_exchange` (which is automatically set).
169
-
170
- In the `When`, use the `call` method to make the request `@exchange.call`. If problems occur in making the request this should separate such failures from issues with the response.
171
-
172
- In the `Then`, make the assertions from the `@exchange` object.
173
- E.g
174
- ```ruby
175
- expect(@exchange['message']).to include 'success'
176
- expect(@exchange.status_code).to eq 200
177
- ```
178
-
179
- ### Authentication
180
-
181
- See [the wiki](https://gitlab.com/samuel-garratt/soaspec/wikis/Authentication) for details.
182
-
183
- ## Logging
184
-
185
- By default traffic is logged to a file in the `logs` folder called `traffic_DATETIME.log`.
186
-
187
- The `SpecLogger` class is responsible for handling all the logs.
188
-
189
- To change the output file location to 'custom.log':
190
- ```ruby
191
- Soaspec::SpecLogger.traffic_file = 'custom.log'
192
- ```
193
-
194
- To change the folder the default log is:
195
-
196
- ```ruby
197
- Soaspec::SpecLogger.traffic_folder = 'custom_folder'
198
- ```
199
-
200
- To disable logging to a file set the 'output_to_file' to 'false'.
201
- ```ruby
202
- Soaspec::SpecLogger.output_to_file = false
203
- ```
204
- There is a similar parameter to logging to the terminal, STDOUT (by default false).
205
- You can also change the color of this output with the `terminal_color` attribute.
206
- ```ruby
207
- Soaspec::SpecLogger.output_to_terminal = true
208
- Soaspec::SpecLogger.terminal_color = :magenta
209
- ```
210
-
211
- ## Learning more
212
-
213
- Looking at the website [here](https://samuel-garratt.gitlab.io/soaspec/)
214
-
215
- ## Development
216
-
217
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
218
-
219
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
220
-
221
- ## Contributing
222
-
223
- Bug reports and pull requests are welcome on GitLab at https://gitlab.com/samuel-garratt/soaspec. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
224
-
225
- ## License
226
-
227
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
228
-
229
- ## Code of Conduct
230
-
231
- Everyone interacting in the Soaspec project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://gitlab.com/samuel-garratt/soaspec/blob/master/CODE_OF_CONDUCT.md).
1
+ # Soaspec
2
+
3
+ This gem helps to represent multiple API tests against a backend briefly, concisely and clearly.
4
+
5
+ ![Soaspec example](images/basic_demo.gif)
6
+ > Example showing how a REST 'get' call can be made and it's response extracted.
7
+
8
+ [![Build Status](https://gitlab.com/samuel-garratt/soaspec/badges/master/build.svg)](https://gitlab.com/samuel-garratt/soaspec/pipelines)
9
+ [![Coverage](https://gitlab.com/samuel-garratt/soaspec/badges/master/coverage.svg)](https://samuel-garratt.gitlab.io/soaspec/coverage)
10
+
11
+ It is essentially a wrapper around the Savon and RestClient gems, adding useful functionality including
12
+
13
+ * Creating multiple API calls from the same base configuration through the use of an `ExchangeHandler` class
14
+ * Extracting values from response body's through either `XPath` or `JSONPath`
15
+ * Building up a custom RSpec `success scenario` shared example to reuse common tests on an API
16
+ * Methods simplifying setting and extracting values from a `Request/Response` pair (`Exchange`)
17
+ * Waiting for a particular response from an API by polling it
18
+ * Representing paths to values from a response with business-meaningful method names
19
+ * Generating initial code for testing an API with `soaspec new`
20
+ * Accessing and utilising `oauth2` access tokens
21
+ * Hosting a `virtual_server` that simulates REST & SOAP responses from an API
22
+
23
+ ## Installation
24
+
25
+ Add this line to your application's Gemfile:
26
+
27
+ ```ruby
28
+ gem 'soaspec'
29
+ ```
30
+
31
+ And then execute:
32
+
33
+ $ bundle
34
+
35
+ Or install it yourself as:
36
+
37
+ $ gem install soaspec
38
+
39
+ [Things to be done](Todo.md)
40
+
41
+ ## Getting Started
42
+ ### Git book
43
+ A book is in progress that will walk through creating an API test in Ruby and
44
+ how you can manage different variations of API tests in Soaspec. You can see
45
+ the draft [here](https://samuel-garratt.gitlab.io/soaspec_book/)
46
+
47
+ ### Create a new test suite using RSpec
48
+ To create a new test suite using gem you can use the `soaspec` binary/executable.
49
+
50
+ Example:
51
+
52
+ ```
53
+ mkdir 'api_test'
54
+ cd 'api_test'
55
+ soaspec new [rest/soap]
56
+ bundle install
57
+ ```
58
+
59
+ This creates some RSpec tests for a sample SOAP/REST service.
60
+ It creates tests that can be run through the `spec` Rake task. To understand
61
+ what the tests are doing, please read the [usage section](#usage).
62
+
63
+ ```
64
+ rake spec
65
+ ```
66
+
67
+ ### Create an ExchangeHandler representing an API
68
+ To create a new handler from the command line use `soaspec add`.
69
+ E.g to generate handler for MyApi
70
+ ```
71
+ soaspec add rest MyApi
72
+ ```
73
+
74
+ `soaspec generate` can be used to help generate an exchange handler. This
75
+ will open a browser from which you can enter parameters and have an `ExchangeHandler`
76
+ generated with the parameters entered.
77
+
78
+ ### Generate test suite from a WSDL
79
+ A test suite can also be generated using a WSDL if a `--wsdl` option is passed to
80
+ the `soaspec generate` command.
81
+ This is still in trial period and will be finished probably after Savon 3 is more stable as
82
+ it can make use of its generation of a sample request.
83
+
84
+ ## Usage
85
+
86
+ * SOAP - this uses Savon behind the scenes. Some defaults are overridden. Please see 'soap_handler.rb'-'default_options' method
87
+ for such defaults. When describing an API override this in 'savon_options' method
88
+ * REST - this uses the resource class from the Rest-Client gem behind the scenes.
89
+
90
+ See [spec](spec) and [features](features) for example of usage.
91
+
92
+ ### ExchangeHandler
93
+
94
+ To start with, create a class inheriting from a ‘Handler’ class for each web service that needs testing.
95
+ In this class you define the common parameters used for testing it.
96
+
97
+ For example:
98
+
99
+ ```ruby
100
+ # Classes are set up through inheriting from either `Soaspec::RestHandler` or `Soaspec::SoapHandler`
101
+ class PuppyService < Soaspec::RestHandler
102
+ # Set default headers for all `Exchanges` using this class
103
+ headers accept: 'application/json', content_type: 'application/json'
104
+
105
+ # URL for which all requests using this class will start with
106
+ base_url 'http://petstore.swagger.io/v2/pet'
107
+
108
+ # Accessing parts of a response
109
+
110
+ # Define a method 'id' that can be obtained with either XPATH '//id' or JSONPath '$..id'
111
+ element :id, :id
112
+ # Define method to obtain a category id through JSON Path
113
+ element :category_id, '$..category.id'
114
+ end
115
+ ```
116
+
117
+ > You can easily create a exchange handler with the `soaspec add` command. This will also add comments explaining common methods that can be used
118
+
119
+ ### Exchange
120
+
121
+ After creating the `ExchangeHandler`, you reference this class in creating `Exchange`s (objects that each represent a request / response pair).
122
+ Upon initialization of the Exchange object (or later on through setters), parameters specific to this request are set.
123
+ Most getters of the `Exchange` are on the response & will implicitly trigger the API request to be made.
124
+ Once this request has been made, all following accessors of the response will just use the response of the previous request made.
125
+
126
+ For example, to create a http post using the above `ExchangeHandler` and get parts of it's response.
127
+ ```ruby
128
+ # Create a new Exchange that will post to 'http://petstore.swagger.io/v2/pet' with JSON { "status": "sold" }
129
+ # The 'body' key will convert it's value from a Hash to JSON
130
+ exchange = PuppyService.post(body: { status: 'sold' })
131
+
132
+ # This will trigger the request to be made & return the response, in this case a RestClient::Response object
133
+ response = exchange.response
134
+ # This will reuse the response already received return a value at JSON path $..category.id, throwing an exception if not found
135
+ exchange.category_id
136
+ # This will do the same but using path directly in code
137
+ exchange['$..category.id']
138
+ # Get the HTTP status code of the response
139
+ exchange.status_code
140
+ ```
141
+
142
+ See [Request Body Parameters](https://gitlab.com/samuel-garratt/soaspec/wikis/RequestBodyParameters) for more details on setting a request body.
143
+ See [Creating an Exchange](https://gitlab.com/samuel-garratt/soaspec/wikis/CreatingExchange) for details on how to create an Exchange.
144
+
145
+ ### Virtual Server
146
+
147
+ Soaspec includes a virtual server that returns REST and SOAP responses that can be used when learning or experimenting with API testing.
148
+ The gem itself uses this to test it's own functionality.
149
+
150
+ To start the server, after installing the gem, type
151
+
152
+ ```
153
+ soaspec virtual_server [port_num]
154
+ ```
155
+
156
+ By default it runs on port 4999. This will be used if `port_num` is empty.
157
+
158
+ You can look at the documentation for the web services provided at the rool url (e.g `localhost:4999`).
159
+
160
+ ### RSpec
161
+
162
+ For example:
163
+
164
+ ```ruby
165
+ context PuppyService.new('Order Puppies') do
166
+ describe post(:create_pet, body: { status: 'sold' }) do # Post with status as sold in request
167
+ its(['status']) { is_expected.to eq 'sold' } # Check responses status is sold
168
+ end
169
+ end
170
+ ```
171
+
172
+ #### Tips
173
+
174
+ If you find having a large backtrace on errors or RSpec shared examples such as 'success scenarios' this can shorten the
175
+ backtrace.
176
+
177
+ RSpec.configure do |config|
178
+
179
+ config.backtrace_exclusion_patterns = [
180
+ /rspec/
181
+ ]
182
+ end
183
+
184
+ ### Cucumber
185
+
186
+ If you're using `Cucumber` for testing a single API call then I would
187
+ recommend the following
188
+
189
+ In the `Given` (or background) specify the `Exchange` object.
190
+ Either store this as an instance variable (e.g `@exchange`) or use the global `Soaspec.last_exchange` (which is automatically set).
191
+
192
+ In the `When`, use the `call` method to make the request `@exchange.call`. If problems occur in making the request this should separate such failures from issues with the response.
193
+
194
+ In the `Then`, make the assertions from the `@exchange` object.
195
+ E.g
196
+ ```ruby
197
+ expect(@exchange['message']).to include 'success'
198
+ expect(@exchange.status_code).to eq 200
199
+ ```
200
+
201
+ ### Authentication
202
+
203
+ See [the wiki](https://gitlab.com/samuel-garratt/soaspec/wikis/Authentication) for details.
204
+
205
+ ## Logging
206
+
207
+ By default traffic is logged to a file in the `logs` folder called `traffic_DATETIME.log`.
208
+
209
+ The `SpecLogger` class is responsible for handling all the logs.
210
+
211
+ To change the output file location to 'custom.log':
212
+ ```ruby
213
+ Soaspec::SpecLogger.traffic_file = 'custom.log'
214
+ ```
215
+
216
+ To change the folder the default log is:
217
+
218
+ ```ruby
219
+ Soaspec::SpecLogger.traffic_folder = 'custom_folder'
220
+ ```
221
+
222
+ To disable logging to a file set the 'output_to_file' to 'false'.
223
+ ```ruby
224
+ Soaspec::SpecLogger.output_to_file = false
225
+ ```
226
+ There is a similar parameter to logging to the terminal, STDOUT (by default false).
227
+ You can also change the color of this output with the `terminal_color` attribute.
228
+ ```ruby
229
+ Soaspec::SpecLogger.output_to_terminal = true
230
+ Soaspec::SpecLogger.terminal_color = :magenta
231
+ ```
232
+
233
+ ## Learning more
234
+
235
+ Looking at the website [here](https://samuel-garratt.gitlab.io/soaspec/)
236
+
237
+ ## Development
238
+
239
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
240
+
241
+ To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
242
+
243
+ ## Contributing
244
+
245
+ Bug reports and pull requests are welcome on GitLab at https://gitlab.com/samuel-garratt/soaspec. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
246
+
247
+ ## License
248
+
249
+ The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
250
+
251
+ ## Code of Conduct
252
+
253
+ Everyone interacting in the Soaspec project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://gitlab.com/samuel-garratt/soaspec/blob/master/CODE_OF_CONDUCT.md).