{"__v":27,"_id":"55a470b768c7e20d0036d4d6","category":{"__v":12,"_id":"559b65be8b04e90d00702d58","pages":["559b65bf8b04e90d00702d5a","55a46241ffd44e0d00fca056","55a46f45e75ca60d00a39323","55a470b768c7e20d0036d4d6","55a4a758dad9d00d0071fcba","55b6b6276127b12500364560","55baf505d0736b3100bf1033","55c25ef1f2cff20d006d0b8a","56269a8b44c87f0d00fe6378","56498f62f176080d000c78ac","566f59c4fc3abb0d0020fcd5","567cd2228eb5b20d0021059d"],"project":"559b65bd8b04e90d00702d54","version":"559b65bd8b04e90d00702d57","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-07T05:38:06.409Z","from_sync":false,"order":0,"slug":"chimpjs","title":"Chimp.js"},"parentDoc":null,"project":"559b65bd8b04e90d00702d54","user":"559b658d8b04e90d00702d52","version":{"__v":6,"_id":"559b65bd8b04e90d00702d57","project":"559b65bd8b04e90d00702d54","createdAt":"2015-07-07T05:38:05.890Z","releaseDate":"2015-07-07T05:38:05.890Z","categories":["559b65be8b04e90d00702d58","55a46e7468c7e20d0036d4d1","55a4971be6c2470d002a6483","55a4a690e10ba50d00b40bba","55a4bcf31a5f991700a94066","56cf5c8d336aa60b0086a40d"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["55c74688b9aa4e0d0016c333","55c74c4fb9aa4e0d0016c340","55c7773b476be90d005008ac","56e70165f3b12a3200df22a2","56e9cf7faf392b170035f68c","57650aeac176520e00ea904e","58b04652f634c7370091568c"],"next":{"pages":[],"description":""},"createdAt":"2015-07-14T02:15:19.200Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"mkdir chimp-tutorial\\ncd chimp-tutorial\\nnpm install chimp\\nmkdir features\\nchimp --watch\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nChimp will download any tools it needs and then start watching your files. When it's ready, it will start a Chrome browser for you. Don't close this window as you will use it to see the automation happening.\n\nCreate the file `./chimp-tutorial/features/search.feature` and paste the following content into it: (note this is not a YAML file it is in Gherkin syntax and not valid YAML)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Feature: Search the Web\\n\\n  As a human\\n  I want to search the web\\n  So I can find information\\n\\n  Scenario: Search for Xolv.io\\n    Given I have visited Google\\n    When I search for \\\"Xolv.io\\\"\\n    Then I see \\\"Xolv.io\\\"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSave this file and you'll see this output in the console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Watching features with tagged with :::at:::dev,@watch,@focus\\n[chimp] Running...\\n\\n0 scenarios\\n0 steps\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nNext add a `@watch` tag just above the scenario as you can see below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"  @watch\\n  Scenario: Search for Xolv.io\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nSave this file again and you'll see this in the console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Running...\\n\\nFeature: Search the Web\\n\\n  As a human\\n  I want to search the web\\n  So I can find information\\n\\n  @watch\\n  Scenario: Search for Xolv.io   # features/search.feature:8\\n    Given I have visited Google  # features/search.feature:9\\n    When I search for \\\"Xolv.io\\\"  # features/search.feature:10\\n    Then I see \\\"Xolv.io\\\"         # features/search.feature:11\\n\\n\\n1 scenario (1 undefined)\\n3 steps (3 undefined)\\n\\nYou can implement step definitions for undefined steps with these snippets:\\n\\nthis.Given(/^I have visited Google$/, function () {\\n  // Write the automation code here\\n\\tpending();\\n});\\n\\nthis.When(/^I search for \\\"([^\\\"]*)\\\"$/, function (arg1) {\\n  // Write the automation code here\\n\\tpending();\\n});\\n\\nthis.Then(/^I see \\\"([^\\\"]*)\\\"$/, function (arg1) {\\n  // Write the automation code here\\n\\tpending();\\n});\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nCucumber.js has just reported to you that you have not implemented step definitions for your scenario and it provided you with some helpful code snips that you can use. So create the file `./chimp-tutorial/features/support/step_defs.js` and copy the code snips into it like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"module.exports = function() {\\n\\n  this.Given(/^I have visited Google$/, function () {\\n    // Write the automation code here\\n    pending();\\n  });\\n\\n  this.When(/^I search for \\\"([^\\\"]*)\\\"$/, function (arg1) {\\n    // Write the automation code here\\n    pending();\\n  });\\n\\n  this.Then(/^I see \\\"([^\\\"]*)\\\"$/, function (arg1) {\\n    // Write the automation code here\\n    pending();\\n  });\\n  \\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Step Definitions Files are Modules\",\n  \"body\": \"Note that the steps definitions files must be wrapped with `module.exports` for Cucumber.js to use them.\"\n}\n[/block]\nSave this file, and now you'll see this in the console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Running...\\n\\n...\\n\\n1 scenario (1 pending)\\n3 steps (1 pending, 2 skipped)\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nCucumber.js is now letting you know that 1 scenario is pending. This is because the first step used `callback.pending`, therefore subsequent steps are skipped.\n\nThe next step is to automate the steps one by one and turn every line into cucumber-green!\n\nEdit the `Given` step in your step definitions file to match the following code:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"this.Given(/^I have visited Google$/, function () {\\n  browser.url('http://google.com');\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWhen you save this file, you will see the browser navigate to `http://google.com` as you instructed it to. You will also see this in the console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Running...\\n\\n...\\n\\n1 scenario (1 pending)\\n3 steps (1 pending, 1 skipped, 1 passed)\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nYay! Our first passing step! Let's take a minute to examine what just happened. \n\nYou have access to `browser`, which an instance of WebdriverIO, and you are using the `url`([docs](http://webdriver.io/api/protocol/url.html)) method. As you can see in its docs, when the `url` method is called with a parameter, it commands the browser to navigate to the provided URL.\n\nWe have two more steps to automate, so edit the `When` step your step definitions file to match the following code:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"this.When(/^I search for \\\"([^\\\"]*)\\\"$/, function (searchTerm) {\\n  browser.setValue('input[name=\\\"q\\\"]', searchTerm);\\n  browser.keys(['Enter']);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave. Now you'll see your browser go to `http://google.com` and it will also search for `\"Xolv.io\"`. You'll also see this in the console:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Running...\\n\\n...\\n\\n1 scenario (1 pending)\\n3 steps (1 pending, 2 passed)\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n2 steps are passing. You're getting there! Let's take another minute to examine this code:\n\nNotice the `searchTerm` parameter being passed in to the step. This is because the regex of the `When` function is extracting anything between quotes defined in the feature file and passing into the parameter of the step definition function. This is how you pass parameters from feature files to the automation layer.\n\nThere are also two new methods being used on the `browser` object. They are `setValue` ([docs](http://webdriver.io/api/action/setValue.html)) and `keys` ([docs](http://webdriver.io/api/protocol/keys.html)). The first method uses the selector `input[name='q']` which targets Google's search box, and the second method sends a sequence of keys. The `'Enter'` keyword is a shortcut for sending the equivalent a Unicode character as you can [see here](https://github.com/webdriverio/webdriverio/blob/master/lib/helpers/constants.js).\n\nLet's automate the final step. Modify the `Then` step in your step definitions file to match the following code:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"this.Then(/^I see \\\"([^\\\"]*)\\\"$/, function (link) {\\n  browser.waitForExist('a=' + link);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nSave this file and the browser will navigate to Google and perform the search and the console will show the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[chimp] Running...\\n\\n...\\n\\n1 scenario (1 passed)\\n3 steps (3 passed)\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nThe whole scenario has passed because all 3 steps passed. Most excellent!\n\nLet's examine the last step. As before, a `link` parameter is being passed in from the feature, and now the `waitForExist` ([docs](http://webdriver.io/api/utility/waitForExist.html)) command is being used from WebdriverIO.\n\nThis command will wait for the element addressed by the selector to exist before continuing. If the element is not found, this method will timeout.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"When working with the DOM, you need to make sure you wait for elements to exist and not assume they are already on the page.\",\n  \"title\": \"Don't assume elements are ready\"\n}\n[/block]\nHopefully the above tutorial gives you a taste of how Chimp helps you drive development from specifications. This tutorial only scratches the surface of what you can do with Chimp. \n\nYou should check out CucumberJS and learn more about the [Gherkin syntax](https://cucumber.io/docs/reference#gherkin). For example, you can use [simpler strings](https://github.com/cucumber/cucumber-js#strings-instead-of-regular-expressions) with placeholders instead of regular expressions:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"this.When('I search for \\\"$string\\\"', function (searchTerm) { ... });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou should check out [WebdriverIO's API guide](http://webdriver.io/api.html) to see all the things you can do with the `browser` object.\n\nYou should also checkout the [Jasmine Expect](doc:jasmine-expect) and master them so you can write clean automation steps like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"this.Then(/^they see the heading \\\"([^\\\"]*)\\\"$/, function(heading) {\\n  expect(browser.getText('h1')).toEqual(heading);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou also have access to a `request` inside your step definitions. See the [request API guide](https://github.com/request/request). With this you can automate calls to servers over HTTP and perform tasks such as calling fixtures and setting up test data. \n\nFor some more examples of what you can do with Chimp, [check out Letterpress](https://github.com/xolvio/Letterpress/tree/master/app/tests/cucumber/features) which has plenty of examples of automation.\n\n---\n\n<a href=\"http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch\"><img src=\"https://files.readme.io/764e495-qualityfasterbook-commas.small.png\" width=\"200\" align=\"right\" /></a>\n##Learn the Fundamentals of Testing, Specifications and Become a Chimp Ninja!\n[Checkout our new book](http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch) where you can learn how to can use Chimp across the Full Stack from CUCUMBER to React, Node.JS, Mocha, Meteor and more.\n\n\n**[Quality, Faster.](http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch)** By Sam Hatoum, creator of Chimp.","excerpt":"A gentle intro","slug":"tutorial","type":"basic","title":"Tutorial - Cucumber"}

Tutorial - Cucumber

A gentle intro

[block:code] { "codes": [ { "code": "mkdir chimp-tutorial\ncd chimp-tutorial\nnpm install chimp\nmkdir features\nchimp --watch", "language": "shell" } ] } [/block] Chimp will download any tools it needs and then start watching your files. When it's ready, it will start a Chrome browser for you. Don't close this window as you will use it to see the automation happening. Create the file `./chimp-tutorial/features/search.feature` and paste the following content into it: (note this is not a YAML file it is in Gherkin syntax and not valid YAML) [block:code] { "codes": [ { "code": "Feature: Search the Web\n\n As a human\n I want to search the web\n So I can find information\n\n Scenario: Search for Xolv.io\n Given I have visited Google\n When I search for \"Xolv.io\"\n Then I see \"Xolv.io\"", "language": "text" } ] } [/block] Save this file and you'll see this output in the console: [block:code] { "codes": [ { "code": "[chimp] Watching features with tagged with @dev,@watch,@focus\n[chimp] Running...\n\n0 scenarios\n0 steps", "language": "shell" } ] } [/block] Next add a `@watch` tag just above the scenario as you can see below: [block:code] { "codes": [ { "code": " @watch\n Scenario: Search for Xolv.io", "language": "text" } ] } [/block] Save this file again and you'll see this in the console: [block:code] { "codes": [ { "code": "[chimp] Running...\n\nFeature: Search the Web\n\n As a human\n I want to search the web\n So I can find information\n\n @watch\n Scenario: Search for Xolv.io # features/search.feature:8\n Given I have visited Google # features/search.feature:9\n When I search for \"Xolv.io\" # features/search.feature:10\n Then I see \"Xolv.io\" # features/search.feature:11\n\n\n1 scenario (1 undefined)\n3 steps (3 undefined)\n\nYou can implement step definitions for undefined steps with these snippets:\n\nthis.Given(/^I have visited Google$/, function () {\n // Write the automation code here\n\tpending();\n});\n\nthis.When(/^I search for \"([^\"]*)\"$/, function (arg1) {\n // Write the automation code here\n\tpending();\n});\n\nthis.Then(/^I see \"([^\"]*)\"$/, function (arg1) {\n // Write the automation code here\n\tpending();\n});", "language": "shell" } ] } [/block] Cucumber.js has just reported to you that you have not implemented step definitions for your scenario and it provided you with some helpful code snips that you can use. So create the file `./chimp-tutorial/features/support/step_defs.js` and copy the code snips into it like this: [block:code] { "codes": [ { "code": "module.exports = function() {\n\n this.Given(/^I have visited Google$/, function () {\n // Write the automation code here\n pending();\n });\n\n this.When(/^I search for \"([^\"]*)\"$/, function (arg1) {\n // Write the automation code here\n pending();\n });\n\n this.Then(/^I see \"([^\"]*)\"$/, function (arg1) {\n // Write the automation code here\n pending();\n });\n \n}", "language": "javascript" } ] } [/block] [block:callout] { "type": "info", "title": "Step Definitions Files are Modules", "body": "Note that the steps definitions files must be wrapped with `module.exports` for Cucumber.js to use them." } [/block] Save this file, and now you'll see this in the console: [block:code] { "codes": [ { "code": "[chimp] Running...\n\n...\n\n1 scenario (1 pending)\n3 steps (1 pending, 2 skipped)", "language": "shell" } ] } [/block] Cucumber.js is now letting you know that 1 scenario is pending. This is because the first step used `callback.pending`, therefore subsequent steps are skipped. The next step is to automate the steps one by one and turn every line into cucumber-green! Edit the `Given` step in your step definitions file to match the following code: [block:code] { "codes": [ { "code": "this.Given(/^I have visited Google$/, function () {\n browser.url('http://google.com');\n});", "language": "javascript" } ] } [/block] When you save this file, you will see the browser navigate to `http://google.com` as you instructed it to. You will also see this in the console: [block:code] { "codes": [ { "code": "[chimp] Running...\n\n...\n\n1 scenario (1 pending)\n3 steps (1 pending, 1 skipped, 1 passed)", "language": "shell" } ] } [/block] Yay! Our first passing step! Let's take a minute to examine what just happened. You have access to `browser`, which an instance of WebdriverIO, and you are using the `url`([docs](http://webdriver.io/api/protocol/url.html)) method. As you can see in its docs, when the `url` method is called with a parameter, it commands the browser to navigate to the provided URL. We have two more steps to automate, so edit the `When` step your step definitions file to match the following code: [block:code] { "codes": [ { "code": "this.When(/^I search for \"([^\"]*)\"$/, function (searchTerm) {\n browser.setValue('input[name=\"q\"]', searchTerm);\n browser.keys(['Enter']);\n});", "language": "javascript" } ] } [/block] Save. Now you'll see your browser go to `http://google.com` and it will also search for `"Xolv.io"`. You'll also see this in the console: [block:code] { "codes": [ { "code": "[chimp] Running...\n\n...\n\n1 scenario (1 pending)\n3 steps (1 pending, 2 passed)", "language": "shell" } ] } [/block] 2 steps are passing. You're getting there! Let's take another minute to examine this code: Notice the `searchTerm` parameter being passed in to the step. This is because the regex of the `When` function is extracting anything between quotes defined in the feature file and passing into the parameter of the step definition function. This is how you pass parameters from feature files to the automation layer. There are also two new methods being used on the `browser` object. They are `setValue` ([docs](http://webdriver.io/api/action/setValue.html)) and `keys` ([docs](http://webdriver.io/api/protocol/keys.html)). The first method uses the selector `input[name='q']` which targets Google's search box, and the second method sends a sequence of keys. The `'Enter'` keyword is a shortcut for sending the equivalent a Unicode character as you can [see here](https://github.com/webdriverio/webdriverio/blob/master/lib/helpers/constants.js). Let's automate the final step. Modify the `Then` step in your step definitions file to match the following code: [block:code] { "codes": [ { "code": "this.Then(/^I see \"([^\"]*)\"$/, function (link) {\n browser.waitForExist('a=' + link);\n});", "language": "javascript" } ] } [/block] Save this file and the browser will navigate to Google and perform the search and the console will show the following: [block:code] { "codes": [ { "code": "[chimp] Running...\n\n...\n\n1 scenario (1 passed)\n3 steps (3 passed)", "language": "shell" } ] } [/block] The whole scenario has passed because all 3 steps passed. Most excellent! Let's examine the last step. As before, a `link` parameter is being passed in from the feature, and now the `waitForExist` ([docs](http://webdriver.io/api/utility/waitForExist.html)) command is being used from WebdriverIO. This command will wait for the element addressed by the selector to exist before continuing. If the element is not found, this method will timeout. [block:callout] { "type": "info", "body": "When working with the DOM, you need to make sure you wait for elements to exist and not assume they are already on the page.", "title": "Don't assume elements are ready" } [/block] Hopefully the above tutorial gives you a taste of how Chimp helps you drive development from specifications. This tutorial only scratches the surface of what you can do with Chimp. You should check out CucumberJS and learn more about the [Gherkin syntax](https://cucumber.io/docs/reference#gherkin). For example, you can use [simpler strings](https://github.com/cucumber/cucumber-js#strings-instead-of-regular-expressions) with placeholders instead of regular expressions: [block:code] { "codes": [ { "code": "this.When('I search for \"$string\"', function (searchTerm) { ... });", "language": "javascript" } ] } [/block] You should check out [WebdriverIO's API guide](http://webdriver.io/api.html) to see all the things you can do with the `browser` object. You should also checkout the [Jasmine Expect](doc:jasmine-expect) and master them so you can write clean automation steps like this: [block:code] { "codes": [ { "code": "this.Then(/^they see the heading \"([^\"]*)\"$/, function(heading) {\n expect(browser.getText('h1')).toEqual(heading);\n});", "language": "javascript" } ] } [/block] You also have access to a `request` inside your step definitions. See the [request API guide](https://github.com/request/request). With this you can automate calls to servers over HTTP and perform tasks such as calling fixtures and setting up test data. For some more examples of what you can do with Chimp, [check out Letterpress](https://github.com/xolvio/Letterpress/tree/master/app/tests/cucumber/features) which has plenty of examples of automation. --- <a href="http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch"><img src="https://files.readme.io/764e495-qualityfasterbook-commas.small.png" width="200" align="right" /></a> ##Learn the Fundamentals of Testing, Specifications and Become a Chimp Ninja! [Checkout our new book](http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch) where you can learn how to can use Chimp across the Full Stack from CUCUMBER to React, Node.JS, Mocha, Meteor and more. **[Quality, Faster.](http://quality.xolv.io/?utm_source=XolvOSS&utm_medium=OSSDocs&utm_content=ChimpRM-Footer&utm_campaign=QFLaunch)** By Sam Hatoum, creator of Chimp.