{"__v":0,"_id":"57c848434434350e005099be","category":{"__v":60,"_id":"569002f19ebef90d0087289d","pages":["56900352769f210d00132595","5690047121fcf0190071d943","569004924719c119002ce654","569004ceb700ce0d002f4b94","569023e518c3920d00be8b37","569023f748df220d004ca215","5690240af7eb9a0d00f4465d","5690241b48df220d004ca217","5690243e48df220d004ca219","56902453741e9c0d00af2fb5","56902463efcc380d0043a5a1","5690247b18c3920d00be8b39","56902492f7eb9a0d00f4465f","569024a16c49d70d00f18075","569024b2efcc380d0043a5a3","569024cc48df220d004ca21b","569024ea18c3920d00be8b3b","5690258618c3920d00be8b3f","5690259bf7eb9a0d00f44662","569025b06c49d70d00f18077","569029b418c3920d00be8b43","569029d4f7eb9a0d00f44667","569029e8e056c80d00fdec58","569029fb48df220d004ca221","56902a1c18c3920d00be8b46","56902a45f7eb9a0d00f44669","56902a6be056c80d00fdec5a","56902a78f7eb9a0d00f4466b","56902a8848df220d004ca224","56902aa018c3920d00be8b4b","56902ace6c49d70d00f18085","56902ae0741e9c0d00af2fc6","56902aee48df220d004ca226","56902af8f7eb9a0d00f44674","56902b26efcc380d0043a5b1","56902b8148df220d004ca22a","56902ba918c3920d00be8b55","56902bb96c49d70d00f1808b","56902bc818c3920d00be8b57","56902bd518c3920d00be8b59","56902be218c3920d00be8b5b","56902bf66c49d70d00f1808e","56902c05e056c80d00fdec5d","56902c196c49d70d00f18090","56902c2648df220d004ca22d","56902c34f7eb9a0d00f44678","56902c5518c3920d00be8b5d","56902c62741e9c0d00af2fcc","56902cde48df220d004ca230","56902cea741e9c0d00af2fcf","56902d0ae056c80d00fdec60","56902d20efcc380d0043a5b4","56902d3448df220d004ca232","5696c3fbf9203821005fe2fb","5696c3fb9e2d000d00947ab0","5696c3fbf9203821005fe2fa","5697efee8d2a770d00d2fd17","569802611c4dc823005426c7","56a65c82b3ffe00d00156eaf","56f01f88332da41700f24b74"],"project":"568fde81b700ce0d002f4b43","version":"568fde82b700ce0d002f4b46","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-08T18:41:53.562Z","from_sync":false,"order":1,"slug":"commands","title":"Commands"},"parentDoc":null,"project":"568fde81b700ce0d002f4b43","user":"568fffce769f210d0013258f","version":{"__v":23,"_id":"568fde82b700ce0d002f4b46","project":"568fde81b700ce0d002f4b43","createdAt":"2016-01-08T16:06:26.373Z","releaseDate":"2016-01-08T16:06:26.373Z","categories":["568fde82b700ce0d002f4b47","568ff0e504440a1700e4cbbd","569002f19ebef90d0087289d","569004f4769f210d00132599","5690056d9ebef90d008728a0","569005d394c5030d0028813a","5690067804440a1700e4cbe2","569137eb3c4f510d00ec9b92","56913815e56a790d008dbfe3","569138ba3c4f510d00ec9b93","5691392f3c4f510d00ec9b94","56913bbe72f2810d007e4cb0","56933b8d6ebadc0d005b71d2","56933b8d6ebadc0d005b71d3","569564facaa32519009c41e6","5696a319b6d61f0d00acfb40","5696a319a857080d0082e8e8","5697efe43503e40d0061f4d1","5697efe48d2a770d00d2fd16","569e9597ffccd10d00a05c59","56a7a1523d33bc2100793d5c","56a7a32ecf6d771700baeee8","56b8b0f7ddeb231700e69825"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"bar","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-01T15:24:51.216Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":43,"body":"Reads a file and returns its contents. JSON is automatically parsed into JavaScript.\n\n| | |\n|--- | --- |\n| **Returns** | the contents of the file |\n| **Timeout** | `cy.readFile` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#section-timeouts) |\n\n***\n\n# [cy.readFile( *filePath* )](#section-usage)\n\nReads the file at the `filePath`. The `filePath` is relative to the project's root.\n\n***\n\n# [cy.readFile( *filePath*, *encoding* )](#section-specify-encoding)\n\nReads the file at the `filePath` with the `encoding`. The `filePath` is relative to the project's root.\n\n***\n\n# Options\n\nPass in an options object to change the default behavior of `cy.readFile`.\n\n**[cy.readFile( *filePath*, *options* )](#options-usage)**\n\n**[cy.readFile( *filePath*, *encoding*, *options* )](#options-usage)**\n\nOption | Default | Notes\n--- | --- | ---\n`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#section-timeouts) | Total time to wait for the `cy.readFile` command to be processed\n\n***\n\n# Usage\n\n## Read a `txt` file\n\nFor any file other than JSON, the contents of the file are returned.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// message.txt contains:\\n// Hello World\\n\\ncy.readFile(\\\"path/to/message.txt\\\").then(function (text) {\\n  expect(text).to.equal(\\\"Hello World\\\")   // true\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n## Read a `json` file\n\nFor JSON, the contents are parsed into JavaScript and returned.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// data.json contains:\\n// {\\n//   \\\"name\\\": \\\"Eliza\\\",\\n//   \\\"email\\\": \\\"eliza:::at:::example.com\\\"\\n// }\\n\\ncy.readFile(\\\"path/to/data.json\\\").then(function (user) {\\n  // user will equal:\\n  // {\\n  //   name: \\\"Eliza\\\",\\n  //   email: \\\"eliza@example.com\\\"\\n  // }\\n  expect(user.name).to.equal(\\\"Eliza\\\")\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n## Specify encoding\n\nSpecify the encoding with the second argument.\n\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.readFile(\\\"path/to/logo.png\\\", \\\"base64\\\").then(function (logo) {\\n  // logo will be encoded as base64\\n  // and should look something like this:\\n  // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...\\n})\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe following encodings are supported:\n\n* `ascii`\n* `base64`\n* `binary`\n* `hex`\n* `latin1`\n* `utf8`\n* `utf-8`\n* `ucs2`\n* `ucs-2`\n* `utf16le`\n* `utf-16le`\n\n***\n\n# Notes\n\n## Implicit assertion\n\nBy default, `cy.readFile` asserts that the file exists and will fail if it does not exist. It will retry reading the file if it does not initially exist until the file exists or the command times out.\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// will fail after the defaultCommandTimeout is reached\\ncy.readFile('does-not-exist.yaml')\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n## Asserting non-existence\n\nYou can assert that a file does not exist like so:\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"// will pass if the file does not exist\\ncy.readFile('does-not-exist.yaml').should(\\\"not.exist\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\n***\n\n# Command Log\n\n## List the contents of cypress.json\n\n[block:code]\n{\n    \"codes\": [\n        {\n            \"code\": \"cy.readFile(\\\"cypress.json\\\")\\n\",\n            \"language\": \"javascript\"\n        }\n    ]\n}\n[/block]\n\nThe command above will display in the command log as:\n\n<img width=\"521\" alt=\"screen shot of command log\" src=\"https://cloud.githubusercontent.com/assets/1157043/17934353/a02d6c34-69e5-11e6-8f1d-ab1eda17ab3b.png\">\n\nWhen clicking on the `readFile` command within the command log, the console outputs the following:\n\n<img width=\"689\" alt=\"screen shot of console output\" src=\"https://cloud.githubusercontent.com/assets/1157043/17934460/089e0652-69e6-11e6-9f00-7eb282be0d27.png\">\n\n***\n\n# Related\n\n- [writeFile](https://on.cypress.io/api/writeFile)\n- [Creating Fixtures](https://on.cypress.io/guides/creating-fixtures)","excerpt":"Read a file's contents","slug":"readfile","type":"basic","title":"readFile"}

readFile

Read a file's contents

Reads a file and returns its contents. JSON is automatically parsed into JavaScript. | | | |--- | --- | | **Returns** | the contents of the file | | **Timeout** | `cy.readFile` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#section-timeouts) | *** # [cy.readFile( *filePath* )](#section-usage) Reads the file at the `filePath`. The `filePath` is relative to the project's root. *** # [cy.readFile( *filePath*, *encoding* )](#section-specify-encoding) Reads the file at the `filePath` with the `encoding`. The `filePath` is relative to the project's root. *** # Options Pass in an options object to change the default behavior of `cy.readFile`. **[cy.readFile( *filePath*, *options* )](#options-usage)** **[cy.readFile( *filePath*, *encoding*, *options* )](#options-usage)** Option | Default | Notes --- | --- | --- `timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#section-timeouts) | Total time to wait for the `cy.readFile` command to be processed *** # Usage ## Read a `txt` file For any file other than JSON, the contents of the file are returned. [block:code] { "codes": [ { "code": "// message.txt contains:\n// Hello World\n\ncy.readFile(\"path/to/message.txt\").then(function (text) {\n expect(text).to.equal(\"Hello World\") // true\n})\n", "language": "javascript" } ] } [/block] ## Read a `json` file For JSON, the contents are parsed into JavaScript and returned. [block:code] { "codes": [ { "code": "// data.json contains:\n// {\n// \"name\": \"Eliza\",\n// \"email\": \"eliza@example.com\"\n// }\n\ncy.readFile(\"path/to/data.json\").then(function (user) {\n // user will equal:\n // {\n // name: \"Eliza\",\n // email: \"eliza@example.com\"\n // }\n expect(user.name).to.equal(\"Eliza\")\n})\n", "language": "javascript" } ] } [/block] ## Specify encoding Specify the encoding with the second argument. [block:code] { "codes": [ { "code": "cy.readFile(\"path/to/logo.png\", \"base64\").then(function (logo) {\n // logo will be encoded as base64\n // and should look something like this:\n // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...\n})\n", "language": "javascript" } ] } [/block] The following encodings are supported: * `ascii` * `base64` * `binary` * `hex` * `latin1` * `utf8` * `utf-8` * `ucs2` * `ucs-2` * `utf16le` * `utf-16le` *** # Notes ## Implicit assertion By default, `cy.readFile` asserts that the file exists and will fail if it does not exist. It will retry reading the file if it does not initially exist until the file exists or the command times out. [block:code] { "codes": [ { "code": "// will fail after the defaultCommandTimeout is reached\ncy.readFile('does-not-exist.yaml')\n", "language": "javascript" } ] } [/block] ## Asserting non-existence You can assert that a file does not exist like so: [block:code] { "codes": [ { "code": "// will pass if the file does not exist\ncy.readFile('does-not-exist.yaml').should(\"not.exist\")\n", "language": "javascript" } ] } [/block] *** # Command Log ## List the contents of cypress.json [block:code] { "codes": [ { "code": "cy.readFile(\"cypress.json\")\n", "language": "javascript" } ] } [/block] The command above will display in the command log as: <img width="521" alt="screen shot of command log" src="https://cloud.githubusercontent.com/assets/1157043/17934353/a02d6c34-69e5-11e6-8f1d-ab1eda17ab3b.png"> When clicking on the `readFile` command within the command log, the console outputs the following: <img width="689" alt="screen shot of console output" src="https://cloud.githubusercontent.com/assets/1157043/17934460/089e0652-69e6-11e6-9f00-7eb282be0d27.png"> *** # Related - [writeFile](https://on.cypress.io/api/writeFile) - [Creating Fixtures](https://on.cypress.io/guides/creating-fixtures)