1 | ![ApiGeek](docs/favicon.png) ![CI](https://travis-ci.org/apigeek/affirm.svg?branch=master) ![version](https://img.shields.io/github/release/apigeek/affirm.svg?maxAge=2592000) ![dependencies](https://img.shields.io/david/apigeek/affirm.svg?maxAge=2592000) ![apigeeks](https://img.shields.io/badge/apigeeks-are%20awesome-800080.svg)
|
2 |
|
3 | Executable English for Test Teams
|
4 | =================================
|
5 |
|
6 | ApiGeek:Affirm is an BDD test automation and orchestration tool for software teams.
|
7 |
|
8 | Affirm uses English (Gherkin) language to describe and execute test cases for APIs and Web Apps.
|
9 |
|
10 | Test definitions are declarative - which makes them easy to read, write and re-use.
|
11 |
|
12 | Gherkin is human and machine readable - so business analysts, testers, developers and robots can collaborate.
|
13 |
|
14 | Since tests are written in English - every stakeholder (including the Project Sponsor :-) can make sense of them.
|
15 |
|
16 | [View the PDF introduction](docs/Intro.pdf).
|
17 |
|
18 | I want to automate testing
|
19 | ==========================
|
20 |
|
21 | With Affirm, you write your test cases in a simplified dialect of English - called Gherkin.
|
22 |
|
23 | Traditional test scripts are often unreadable by our stakeholders and even ourselves.
|
24 |
|
25 | Affirm uses executable English instructions - actions and assertions - that are easy to read, write and socialise.
|
26 |
|
27 | Features are lists of related scenarios. It's the scenario's that do all the heavy lifting.
|
28 |
|
29 | A scenario describes your pre-conditions, actions and outcomes in a way that is both human and machine friendly.
|
30 |
|
31 | I want to understand Gherkin
|
32 | ============================
|
33 |
|
34 | The Gherkin (BDD) notation for a feature / scenario is:
|
35 |
|
36 | Feature: Basic Examples
|
37 |
|
38 | Scenario: An example
|
39 | GIVEN some context
|
40 | WHEN an action is performed
|
41 | THEN an outcome is expected
|
42 |
|
43 | The text following the keyword (GIVEN | WHEN | THEN) needs to match a phrase/pattern from a vocabulary.
|
44 |
|
45 | New features can be created using any simple text editor - where you'd use ApiGeek:Affirm's extensible vocabulary to write them.
|
46 |
|
47 | You can download pre-packaged vocabularies (called Dialects) and/or roll your own with simple Javascript.
|
48 |
|
49 | I want to see a working example
|
50 | ===============================
|
51 |
|
52 | ApiGeek:Affirm's features are collections of individual test scenarios.
|
53 |
|
54 | To improve readability, the keyword AND can be used instead in place of the verbs above.
|
55 |
|
56 | You can influence what ApiGeek:Affirm understands using @dialect annotations.
|
57 |
|
58 | @dialects=webapi
|
59 | Feature: Verify that Google is accessible
|
60 |
|
61 | Background: Google Scenarios
|
62 |
|
63 | Given I am googling
|
64 |
|
65 | Scenario: Request Google homepage - with redirects
|
66 |
|
67 | Given I enable redirects
|
68 | When I GET http://google.com
|
69 | Then response code should be 200
|
70 |
|
71 | @target=google
|
72 | Scenario: Request Google homepage - no redirect
|
73 |
|
74 | Given I disable redirects
|
75 | When I GET /
|
76 | Then response code should be 3xx
|
77 |
|
78 | I want to test-drive ApiGeek:Affirm
|
79 | ======================================
|
80 |
|
81 | ApiGeek:Affirm is built using NodeJS. If you're new to node, pre-read [Getting Started](https://www.npmjs.com/package/ApiGeek-dialect/tutorial).
|
82 |
|
83 | You install ApiGeek:Affirm as a system-wide CLI command:
|
84 |
|
85 | $ npm install apigeek-affirm -g
|
86 |
|
87 | To run it simply type:
|
88 |
|
89 | $ affirm
|
90 |
|
91 | However, It won't do much else until we provide some feature scenarios.
|
92 |
|
93 | By default, ApiGeek:Affirm looks for ".feature" files recursively, starting in the current directory.
|
94 |
|
95 | I want to create my first feature
|
96 | =================================
|
97 |
|
98 | 1) To quickly create a few examples in the ./features folder, type:
|
99 |
|
100 | $ affirm --example
|
101 |
|
102 | This will create the ./features folder and copy some simple examples.
|
103 |
|
104 | It will also write your default configuration to ./apigeek.json
|
105 |
|
106 | It won't damage if you run it again, except re-save your ./apigeek.json config.
|
107 |
|
108 | Or, you can just create the ./features folder and a default "apigeek.json" without the examples:
|
109 |
|
110 | $ affirm --initialize
|
111 |
|
112 | 2) To execute your example ".feature" files, type:
|
113 |
|
114 | $ affirm
|
115 |
|
116 | 3) If something goes wrong, enable the built-in debugger.
|
117 |
|
118 | $ export DEBUG=apigeek*
|
119 | $ affirm
|
120 |
|
121 | Now, the output is verbose and colour-coded to make your life easier.
|
122 |
|
123 | To turn off debugging, type:
|
124 |
|
125 | $ export DEBUG=
|
126 | $ affirm
|
127 |
|
128 | I want to learn some vocabulary
|
129 | ===============================
|
130 |
|
131 | ApiGeek:Affirm ships with few default vocabularies - variables, files, web apis, web apps, etc.
|
132 |
|
133 | To discover what phrases exist in the vocabularies, type:
|
134 |
|
135 | $ affirm --knows
|
136 |
|
137 | Let's create a trivial example of a hypothetical test case.
|
138 |
|
139 | Scenario: Trivial Test
|
140 |
|
141 | Given I am testing debug
|
142 | When debug works
|
143 | And I succeed
|
144 |
|
145 | The steps are executed in sequence.
|
146 |
|
147 | The GIVEN steps setup pre-conditions. The "Given I am $acting" phrase doesn't do much - except communicate intentions.
|
148 |
|
149 | The "WHEN ... " steps do useful work that result in desirable outcomes. For example: writing a file, requesting a web page, etc.
|
150 |
|
151 | In this example, we simply write a debug message to the console, so let's turn on debug output.
|
152 |
|
153 | $ export DEBUG=apigeek*
|
154 |
|
155 | You can adjust the logging scope - to see only Web API messages, use:
|
156 |
|
157 | $ export DEBUG=apigeek:files
|
158 |
|
159 | The "THEN ..." steps make assertions, that is they test that conditions are met. For example, you can use arbitrary Javascript if necessary:
|
160 |
|
161 | Then I assert $some_javascript
|
162 |
|
163 | The "I succeed", "I pass" always meet their conditions. The inverse "I fail" forces the scenario to abort and report it's failure.
|
164 |
|
165 | I want to learn more about ApiGeek:Affirm
|
166 | ============================================
|
167 |
|
168 | For runtime options, type:
|
169 |
|
170 | $ affirm -h
|
171 |
|
172 | For more information:
|
173 |
|
174 | [Example Features](features/).
|
175 |
|
176 | [Basic Dialect](docs/vocab.md).
|
177 |
|
178 | [Advanced Dialect](docs/advanced.md).
|
179 |
|
180 | [Something Went Wrong](docs/errors.md).
|
181 |
|
182 | [Web API Dialect](https://github.com/apigeek/dialect-webapi/blob/master/vocab.md).
|
183 |
|
184 | [Web API Advanced](https://github.com/apigeek/dialect-webapi/blob/master/advanced.md).
|
185 |
|
186 | [Web Apps Dialect](https://github.com/apigeek/dialect-webapp/blob/master/vocab.md).
|
187 |
|
188 | [Web Apps Advanced](https://github.com/apigeek/dialect-webapp/blob/master/advanced.md).
|
189 |
|
190 | I want to organise my work into folders
|
191 | =======================================
|
192 |
|
193 | If your features are in a different location then use the "--features" or "--epics" option to locate them.
|
194 |
|
195 | $ affirm --archive ./my-archive --features ./my-features
|
196 |
|
197 | These folders are not automatically created, they return an error if they're not found.
|
198 |
|
199 | I want to re-use my features in other projects
|
200 | ==============================================
|
201 |
|
202 | ApiGeek:Affirm was designed to support a declarative style so that features are portable.
|
203 |
|
204 | Supplying a different "config" file for each environment allows features to be re-used across multiple environments.
|
205 |
|
206 | For example, features can adapt to dev, QA and live environments - injecting hostnames, credentials, etc as required.
|
207 |
|
208 | Most Dialects configure themselves automatically.
|
209 |
|
210 | If yours doesn't then there is alternative - use {{mustache}} templates to modify statements prior to execution.
|
211 |
|
212 | Given I login as {{scope.actor}}
|
213 |
|
214 | In this way, your BDD features are neatly abstracted from your runtime configuration.
|
215 |
|
216 | To specify a runtime configuration for your features, type:
|
217 |
|
218 | $ affirm --config ./my-context.json
|
219 |
|
220 | By default, ApiGeek:Affirm will try to load a configuration file called "apigeek.json" from your current directory.
|
221 |
|
222 | If no file is found, then sensible default values are defined.
|
223 |
|
224 | I want to do something before every scenario
|
225 | =============================================
|
226 |
|
227 | Backgrounds are similar to scenarios, except they do not support annotations.
|
228 |
|
229 | Any feature can contain a background, in which case the steps that carried out before each scenario.
|
230 |
|
231 |
|
232 | Background: Authenticate
|
233 |
|
234 | GIVEN I login
|
235 | AND I use a valid client certificate
|
236 |
|
237 | I want to know how it works
|
238 | ===========================
|
239 |
|
240 | First, ApiGeek:Affirm parses the command line and initializes the Dialect, Features and Engine components.
|
241 |
|
242 | Next it loads the default dialects. These can be specified on using the APIGEEK_DIALECT environment variable. Dialects can also be
|
243 | specified using --dialect option and within Feature: definitions using the @dialect annotation.
|
244 |
|
245 | Each Dialect instructs the parser (Yadda) to match a set of Gherkin phrases to their related function.
|
246 |
|
247 | The Feature manager converts features and scenarios into executable units.
|
248 |
|
249 | User defined variables are scoped at the feature-level meaning they are shared between scenarios within the same feature.
|
250 |
|
251 | The --config file is used as the basis for internal context variables. They are scoped to each scenario.
|
252 |
|
253 | These variables - such as web requests/responses - can be accessed using the "this." qualifier - with due caution.
|
254 |
|
255 | Next, the Engine runs each feature using the built-in Mocha runner. Results are correlated and output according to your CLI options.
|
256 |
|
257 | I want to add comments
|
258 | ======================
|
259 |
|
260 | It's useful to document your intentions or to prevent a statement from running, for example during development.
|
261 |
|
262 | Simple, place a # before any line and it will be ignored by Affirm.
|
263 |
|
264 | # This is ignored by the parser
|
265 | Scenario: Comments Example
|
266 |
|
267 | Given I am using comments
|
268 | # Then I fail
|
269 | Then I succeed
|
270 |
|
271 | Instead, you should use @skip or @todo before a Feature: or Scenario: definition.
|
272 |
|
273 | An @bug scenario will pass normally (skipped) but fail when --debug is used.
|
274 |
|
275 | @bug=something is broken
|
276 |
|
277 | Scenario: A Bug
|
278 | Given I am a bug
|
279 | Then I fail
|
280 |
|
281 | I want to do run tests on a schedule
|
282 | ====================================
|
283 |
|
284 | Running a "cron job" is familar to DevOps teams who want to schedule regular activities.
|
285 |
|
286 | Apigeek-Affirm has a built-in cron-like scheduler to provide continuous assurance, see [Cron Scheduler](docs/cron.md) for more details.
|
287 |
|
288 | I want to automate everything
|
289 | =============================
|
290 |
|
291 | That is our goal too. We'll continue to address the needs of Enterprise Affirms.
|
292 |
|
293 | Competent software engineers can easily create "blueprints" that capture the patterns, templates and files used to build SDLC artefacts.
|
294 |
|
295 | Then ApiGeek:Affirm can re-use those blueprints to build customised websites, portals, Apps, APIs, mock servers, micro services and more.
|
296 |
|
297 | Please share any custom Blueprints and Dialects so that ApiGeek:Affirm becomes more useful for all of us.
|
298 |
|
299 | If you need support to build or debug your community Blueprints or Dialects, please ask@apigeek.me
|
300 |
|
301 |
|
302 |
|
303 | I want to license ApiGeek:Affirm
|
304 | ================================
|
305 |
|
306 | This software is licensed under the Apache 2 license, quoted below.
|
307 |
|
308 | Copyright 2015-2016 Lee Curtis & Troven 2009-2015
|
309 |
|
310 | Licensed under the Apache License, Version 2.0 (the "License"); you may not
|
311 | use this file except in compliance with the License. You may obtain a copy of
|
312 | the License at
|
313 |
|
314 | [http://www.apache.org/licenses/LICENSE-2.0]
|
315 |
|
316 | Unless required by applicable law or agreed to in writing, software
|
317 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
318 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
319 | License for the specific language governing permissions and limitations under
|
320 | the License.
|
321 |
|