{"__v":1,"_id":"56980d8b3503e40d0061f4fa","category":{"__v":4,"_id":"56954a95fe18811700c9bfdc","pages":["56954a97fe18811700c9c01c","5697efe61c4dc8230054268d","56980d8b3503e40d0061f4fa","569813082cf4060d004eaac3"],"project":"568fde81b700ce0d002f4b43","version":"56954a94fe18811700c9bfda","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-08T17:24:53.954Z","from_sync":false,"order":1,"slug":"getting-started","title":"Getting Started"},"parentDoc":null,"project":"568fde81b700ce0d002f4b43","user":"568fffce769f210d0013258f","version":{"__v":6,"_id":"56954a94fe18811700c9bfda","project":"568fde81b700ce0d002f4b43","createdAt":"2016-01-12T18:48:52.007Z","releaseDate":"2016-01-12T18:48:52.007Z","categories":["56954a95fe18811700c9bfdb","56954a95fe18811700c9bfdc","56954a95fe18811700c9bfdd","56954a95fe18811700c9bfde","56954a95fe18811700c9bfdf","56954a95fe18811700c9bfe0","56954a95fe18811700c9bfe1","56954a95fe18811700c9bfe2","56954a95fe18811700c9bfe3","56954a95fe18811700c9bfe4","5695649fdcaf0d1700cb8721","5696c1168560a60d00e2c1d6","56a7a32e79395317007c1ad6","5898fc3eec49fb0f004c2663","589cc675ea37da23004e05e1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"foo","version_clean":"0.0.0","version":"0.0"},"updates":["581da0d0440e5d0f0018dd53"],"next":{"pages":[],"description":""},"createdAt":"2016-01-14T21:05:15.363Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Contents\n\n- :fa-angle-right: [Folder Structure](#section-folder-structure)\n- :fa-angle-right: [Test Files](#section-test-files)\n- :fa-angle-right: [How to Write Tests](#section-how-to-write-tests)\n  - [BDD Interface](#section-bdd-interface)\n  - [Hooks](#section-hooks)\n  - [Excluding and Including Tests](#section-excluding-and-including-tests)\n  - [Dynamically Generate Tests](#section-dynamically-generate-tests)\n\n***\n\n# Folder Structure\n\nAfter adding a new project, Cypress will automatically scaffold out a suggested folder structure. By default it will create:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"/cypress\\n/cypress/fixtures\\n/cypress/integration\\n/cypress/support\\n\",\n            \"language\": \"text\"\n        }\n    ]\n}\n[/block]\n\nCypress also adds placeholder files to help get you started with examples in each folder.\n\n**Example JSON fixture**\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"/cypress/fixtures/example.json\\n\",\n            \"language\": \"text\"\n        }\n    ]\n}\n[/block]\n\n**Example Integration Test**\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"/cypress/integration/example_spec.js\\n\",\n            \"language\": \"text\"\n        }\n    ]\n}\n[/block]\n\n**Example JavaScript Support Files**\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"/cypress/support/commands.js\\n/cypress/support/defaults.js\\n/cypress/support/index.js\\n\",\n            \"language\": \"text\"\n        }\n    ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"[Check out our example recipe using support files to import common utilities](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/es2015_commonjs_modules_spec.js)\",\n  \"title\": \"Using Support files for common functionality\"\n}\n[/block]\n\n**Configuring Folder Structure**\n\nWhile Cypress allows for configuration of where your tests, fixtures, and support files are located, if you're starting your first project, we recommend you use the above structure.\n\nYou can modify the folder configuration in your `cypress.json`. See [configuration](https://on.cypress.io/guides/configuration) for more detail.\n\n***\n\n# Test Files\n\nTest files may be written as `.js`, `.jsx`, `.coffee`, or `cjsx` files.\n\nCypress supports ES2015, ES2016, ES2017, and JSX. ES2015 modules and CommonJS modules are also supported, so you can `import` or `require` both npm packages and local modules.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"[Check out our example recipe using ES2015 and CommonJS modules](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/es2015_commonjs_modules_spec.js)\",\n  \"title\": \"Importing ES2015 or CommonJS modules\"\n}\n[/block]\n\nTo see an example of every command used in Cypress, open the [`example_spec.js`](https://github.com/cypress-io/cypress-example-kitchensink/blob/master/cypress/integration/example_spec.js) within your `cypress/integration` folder.\n\nTo start writing tests for your app, simply create a new file like `app_spec.js` within your `cypress/integration` folder. Refresh your tests list in the Cypress GUI and your new file should have appeared in the list.\n\n***\n\n# How to Write Tests\n\nCypress is built on top of [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha) and uses its `bdd` interface. Tests you write in Cypress will mostly adhere to this style.\n\nIf you're familiar with writing tests in JavaScript, then writing tests in Cypress will be a breeze.\n\nWe're still working on introductory docs and videos. If you want to see Cypress in action, [check out some examples](https://on.cypress.io/guides/all-example-apps) of applications using Cypress tests and [check out some example recipes we've written](https://github.com/cypress-io/cypress-example-recipes) for special use cases.\n\n## BDD Interface\n\nThe BDD interface borrowed from [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha) provides `describe()`, `context()`, `it()` and `specify()`.\n\n`context()` is identical to `describe()` and `specify()` is identical to `it()`, so choose whatever terminology works best for you.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// -- Start: Our Application Code --\\nfunction add (a, b) {\\n  return a + b\\n}\\n\\nfunction subtract (a, b) {\\n  return a - b\\n}\\n\\nfunction divide (a, b) {\\n  return a / b\\n}\\n\\nfunction multiply (a, b) {\\n  return a * b\\n}\\n// -- End: Our Application Code --\\n\\n// -- Start: Our Cypress Tests --\\ndescribe('Unit test our math functions', function() {\\n  context('math', function() {\\n    it('can add numbers', function() {\\n      expect(add(1, 2)).to.eq(3)\\n    })\\n\\n    it('can subtract numbers', function() {\\n      expect(subtract(5, 12)).to.eq(-7)\\n    })\\n\\n    specify('can divide numbers', function() {\\n      expect(divide(27, 9)).to.eq(3)\\n    })\\n\\n    specify('can muliple numbers', function() {\\n      expect(multiply(5, 4)).to.eq(20)\\n    })\\n  })\\n})\\n// -- End: Our Cypress Tests --\\n\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n## Hooks\n\nCypress also provides hooks (borrowed from [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha)).\n\nThese are helpful to set conditions that you want run before a set of tests or before each test. They're also helpful to clean up conditions after a set of tests or after each test.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"describe('Hooks', function() {\\n  before(function() {\\n    // runs before all tests in this block\\n  })\\n\\n  after(function() {\\n    // runs after all tests in this block\\n  })\\n\\n  beforeEach(function() {\\n    // runs before each test in this block\\n  })\\n\\n  afterEach(function() {\\n    // runs after each test in this block\\n  })\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n**The order of hook and test execution is as follows:**\n\n- All `before()` hooks run (once)\n- Any `beforeEach()` hooks run\n- Tests run\n- Any `afterEach()` hooks run\n- All `after()` hooks run (once)\n\n## Excluding and Including Tests\n\nTo run a specified suite or test simply append `.only()` to the function. All nested suites will also be executed.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// -- Start: Our Application Code --\\nfunction fizzbuzz (num) {\\n  if (num % 3 === 0 && num % 5 === 0) {\\n    return \\\"fizzbuzz\\\"\\n  }\\n\\n  if (num % 3 === 0) {\\n    return \\\"fizz\\\"\\n  }\\n\\n  if (num % 5 === 0) {\\n    return \\\"buzz\\\"\\n  }\\n}\\n// -- End: Our Application Code --\\n\\n// -- Start: Our Cypress Tests --\\ndescribe('Unit Test FizzBuzz', function(){\\n  beforeEach(function(){\\n    this.numsExpectedToEq = (arr, expected) =>\\n      arr.forEach((num) => {\\n        expect(fizzbuzz(num)).to.eq(expected)\\n      })\\n  })\\n\\n  // Only this test and it's beforeEach code would run\\n  it.only('returns \\\"fizz\\\" when number is multiple of 3', function(){\\n    this.numsExpectedToEq([9, 12, 18], \\\"fizz\\\")\\n  })\\n\\n  it('returns \\\"buzz\\\" when number is multiple of 5', function(){\\n    this.numsExpectedToEq([10, 20, 25], \\\"buzz\\\")\\n  })\\n\\n  it('returns \\\"fizzbuzz\\\" when number is multiple of both 3 and 5', function(){\\n    this.numsExpectedToEq([15, 30, 60], \\\"fizzbuzz\\\")\\n  })\\n})\\n\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nTo skip a specified suite or test simply append `.skip()` to the function. All nested suites will also be skipped.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"it.skip('returns \\\"fizz\\\" when number is multiple of 3', function(){\\n  this.numsExpectedToEq([9, 12, 18], \\\"fizz\\\")\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n## Dynamically Generate Tests\n\nYou can dynamically generate tests using JavaScript.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"describe('if your app uses jQuery', function(){\\n  ['mouseover', 'mouseout', 'mouseenter', 'mouseleave'].forEach((event) => {\\n    it('triggers event: ' + event, function(){\\n      // if your app uses jQuery, then we can trigger a jQuery\\n      // event that causes the event callback to fire\\n      cy\\n        .get('#with-jquery').invoke('trigger', event)\\n        .get('#messages').should('contain', 'the event ' + event + 'was fired')\\n    })\\n  })\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe code above will produce a suite with 4 tests:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"> if your app uses jQuery\\n  > triggers event: 'mouseover'\\n  > triggers event: 'mouseout'\\n  > triggers event: 'mouseenter'\\n  > triggers event: 'mouseleave'\\n\",\n            \"language\": \"bash\"\n        }\n    ]\n}\n[/block]","excerpt":"Walkthrough writing your first test","slug":"writing-your-first-test","type":"basic","title":"Writing Your First Test"}

Writing Your First Test

Walkthrough writing your first test

# Contents - :fa-angle-right: [Folder Structure](#section-folder-structure) - :fa-angle-right: [Test Files](#section-test-files) - :fa-angle-right: [How to Write Tests](#section-how-to-write-tests) - [BDD Interface](#section-bdd-interface) - [Hooks](#section-hooks) - [Excluding and Including Tests](#section-excluding-and-including-tests) - [Dynamically Generate Tests](#section-dynamically-generate-tests) *** # Folder Structure After adding a new project, Cypress will automatically scaffold out a suggested folder structure. By default it will create: [block:code] { "codes": [ { "code": "/cypress\n/cypress/fixtures\n/cypress/integration\n/cypress/support\n", "language": "text" } ] } [/block] Cypress also adds placeholder files to help get you started with examples in each folder. **Example JSON fixture** [block:code] { "codes": [ { "code": "/cypress/fixtures/example.json\n", "language": "text" } ] } [/block] **Example Integration Test** [block:code] { "codes": [ { "code": "/cypress/integration/example_spec.js\n", "language": "text" } ] } [/block] **Example JavaScript Support Files** [block:code] { "codes": [ { "code": "/cypress/support/commands.js\n/cypress/support/defaults.js\n/cypress/support/index.js\n", "language": "text" } ] } [/block] [block:callout] { "type": "info", "body": "[Check out our example recipe using support files to import common utilities](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/es2015_commonjs_modules_spec.js)", "title": "Using Support files for common functionality" } [/block] **Configuring Folder Structure** While Cypress allows for configuration of where your tests, fixtures, and support files are located, if you're starting your first project, we recommend you use the above structure. You can modify the folder configuration in your `cypress.json`. See [configuration](https://on.cypress.io/guides/configuration) for more detail. *** # Test Files Test files may be written as `.js`, `.jsx`, `.coffee`, or `cjsx` files. Cypress supports ES2015, ES2016, ES2017, and JSX. ES2015 modules and CommonJS modules are also supported, so you can `import` or `require` both npm packages and local modules. [block:callout] { "type": "info", "body": "[Check out our example recipe using ES2015 and CommonJS modules](https://github.com/cypress-io/cypress-example-recipes/blob/master/cypress/integration/es2015_commonjs_modules_spec.js)", "title": "Importing ES2015 or CommonJS modules" } [/block] To see an example of every command used in Cypress, open the [`example_spec.js`](https://github.com/cypress-io/cypress-example-kitchensink/blob/master/cypress/integration/example_spec.js) within your `cypress/integration` folder. To start writing tests for your app, simply create a new file like `app_spec.js` within your `cypress/integration` folder. Refresh your tests list in the Cypress GUI and your new file should have appeared in the list. *** # How to Write Tests Cypress is built on top of [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha) and uses its `bdd` interface. Tests you write in Cypress will mostly adhere to this style. If you're familiar with writing tests in JavaScript, then writing tests in Cypress will be a breeze. We're still working on introductory docs and videos. If you want to see Cypress in action, [check out some examples](https://on.cypress.io/guides/all-example-apps) of applications using Cypress tests and [check out some example recipes we've written](https://github.com/cypress-io/cypress-example-recipes) for special use cases. ## BDD Interface The BDD interface borrowed from [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha) provides `describe()`, `context()`, `it()` and `specify()`. `context()` is identical to `describe()` and `specify()` is identical to `it()`, so choose whatever terminology works best for you. [block:code] { "codes": [ { "code": "// -- Start: Our Application Code --\nfunction add (a, b) {\n return a + b\n}\n\nfunction subtract (a, b) {\n return a - b\n}\n\nfunction divide (a, b) {\n return a / b\n}\n\nfunction multiply (a, b) {\n return a * b\n}\n// -- End: Our Application Code --\n\n// -- Start: Our Cypress Tests --\ndescribe('Unit test our math functions', function() {\n context('math', function() {\n it('can add numbers', function() {\n expect(add(1, 2)).to.eq(3)\n })\n\n it('can subtract numbers', function() {\n expect(subtract(5, 12)).to.eq(-7)\n })\n\n specify('can divide numbers', function() {\n expect(divide(27, 9)).to.eq(3)\n })\n\n specify('can muliple numbers', function() {\n expect(multiply(5, 4)).to.eq(20)\n })\n })\n})\n// -- End: Our Cypress Tests --\n\n", "language": "javascript" } ] } [/block] ## Hooks Cypress also provides hooks (borrowed from [Mocha](https://on.cypress.io/guides/bundled-tools#section-mocha)). These are helpful to set conditions that you want run before a set of tests or before each test. They're also helpful to clean up conditions after a set of tests or after each test. [block:code] { "codes": [ { "code": "describe('Hooks', function() {\n before(function() {\n // runs before all tests in this block\n })\n\n after(function() {\n // runs after all tests in this block\n })\n\n beforeEach(function() {\n // runs before each test in this block\n })\n\n afterEach(function() {\n // runs after each test in this block\n })\n})\n", "language": "javascript" } ] } [/block] **The order of hook and test execution is as follows:** - All `before()` hooks run (once) - Any `beforeEach()` hooks run - Tests run - Any `afterEach()` hooks run - All `after()` hooks run (once) ## Excluding and Including Tests To run a specified suite or test simply append `.only()` to the function. All nested suites will also be executed. [block:code] { "codes": [ { "code": "// -- Start: Our Application Code --\nfunction fizzbuzz (num) {\n if (num % 3 === 0 && num % 5 === 0) {\n return \"fizzbuzz\"\n }\n\n if (num % 3 === 0) {\n return \"fizz\"\n }\n\n if (num % 5 === 0) {\n return \"buzz\"\n }\n}\n// -- End: Our Application Code --\n\n// -- Start: Our Cypress Tests --\ndescribe('Unit Test FizzBuzz', function(){\n beforeEach(function(){\n this.numsExpectedToEq = (arr, expected) =>\n arr.forEach((num) => {\n expect(fizzbuzz(num)).to.eq(expected)\n })\n })\n\n // Only this test and it's beforeEach code would run\n it.only('returns \"fizz\" when number is multiple of 3', function(){\n this.numsExpectedToEq([9, 12, 18], \"fizz\")\n })\n\n it('returns \"buzz\" when number is multiple of 5', function(){\n this.numsExpectedToEq([10, 20, 25], \"buzz\")\n })\n\n it('returns \"fizzbuzz\" when number is multiple of both 3 and 5', function(){\n this.numsExpectedToEq([15, 30, 60], \"fizzbuzz\")\n })\n})\n\n", "language": "javascript" } ] } [/block] To skip a specified suite or test simply append `.skip()` to the function. All nested suites will also be skipped. [block:code] { "codes": [ { "code": "it.skip('returns \"fizz\" when number is multiple of 3', function(){\n this.numsExpectedToEq([9, 12, 18], \"fizz\")\n})\n", "language": "javascript" } ] } [/block] ## Dynamically Generate Tests You can dynamically generate tests using JavaScript. [block:code] { "codes": [ { "code": "describe('if your app uses jQuery', function(){\n ['mouseover', 'mouseout', 'mouseenter', 'mouseleave'].forEach((event) => {\n it('triggers event: ' + event, function(){\n // if your app uses jQuery, then we can trigger a jQuery\n // event that causes the event callback to fire\n cy\n .get('#with-jquery').invoke('trigger', event)\n .get('#messages').should('contain', 'the event ' + event + 'was fired')\n })\n })\n})\n", "language": "javascript" } ] } [/block] The code above will produce a suite with 4 tests: [block:code] { "codes": [ { "code": "> if your app uses jQuery\n > triggers event: 'mouseover'\n > triggers event: 'mouseout'\n > triggers event: 'mouseenter'\n > triggers event: 'mouseleave'\n", "language": "bash" } ] } [/block]