{
  "doc": {
    "id": "api/commands/readfile",
    "title": "readFile | Cypress Documentation",
    "description": "Read a file and yield its contents in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/readfile.md",
    "version": "24a73f8a97175663aaffd3b016289fb2a523a4ea",
    "updated_at": "2026-05-14T20:17:33.301Z",
    "headings": [
      {
        "id": "api/commands/readfile#readfile",
        "text": "readFile",
        "level": 1
      },
      {
        "id": "api/commands/readfile#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/readfile#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/readfile#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/readfile#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/readfile#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/readfile#text",
        "text": "Text",
        "level": 3
      },
      {
        "id": "api/commands/readfile#read-a-txt-file",
        "text": "Read a .txt file",
        "level": 4
      },
      {
        "id": "api/commands/readfile#json",
        "text": "JSON",
        "level": 3
      },
      {
        "id": "api/commands/readfile#yaml",
        "text": "YAML",
        "level": 3
      },
      {
        "id": "api/commands/readfile#get-translation-data-from-a-yaml-file",
        "text": "Get translation data from a YAML file",
        "level": 4
      },
      {
        "id": "api/commands/readfile#encoding",
        "text": "Encoding",
        "level": 3
      },
      {
        "id": "api/commands/readfile#specify-the-encoding-with-the-second-argument",
        "text": "Specify the encoding with the second argument",
        "level": 4
      },
      {
        "id": "api/commands/readfile#read",
        "text": "Read",
        "level": 4
      },
      {
        "id": "api/commands/readfile#playing-mp3-file",
        "text": "Playing MP3 file",
        "level": 3
      },
      {
        "id": "api/commands/readfile#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/readfile#existence",
        "text": "Existence",
        "level": 3
      },
      {
        "id": "api/commands/readfile#default-file-existence-assertion",
        "text": "Default file existence assertion",
        "level": 4
      },
      {
        "id": "api/commands/readfile#asserting-file-non-existence",
        "text": "Asserting file non-existence",
        "level": 4
      },
      {
        "id": "api/commands/readfile#read-a-file-that-might-not-exist",
        "text": "Read a file that might not exist",
        "level": 4
      },
      {
        "id": "api/commands/readfile#retries",
        "text": "Retries",
        "level": 3
      },
      {
        "id": "api/commands/readfile#automatic-retries",
        "text": "Automatic retries",
        "level": 4
      },
      {
        "id": "api/commands/readfile#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/readfile#requirements-learn-about-chaining-commands",
        "text": "Requirements Learn about chaining commands",
        "level": 3
      },
      {
        "id": "api/commands/readfile#assertions-learn-about-assertions",
        "text": "Assertions Learn about assertions",
        "level": 3
      },
      {
        "id": "api/commands/readfile#timeouts-learn-about-timeouts",
        "text": "Timeouts Learn about timeouts",
        "level": 3
      },
      {
        "id": "api/commands/readfile#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/readfile#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/readfile#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "api/commands/readfile#syntax",
      "doc_id": "api/commands/readfile",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\ncy.readFile(filePath)cy.readFile(filePath, encoding)cy.readFile(filePath, options)cy.readFile(filePath, encoding, options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.readFile('menu.json')\n```\n\n### Arguments\n\n**filePath _(String)_**\n\nA path to a file within the project root (the directory that contains the [Cypress configuration file](/llm/markdown/app/references/configuration.md)).\n\n**encoding _(String)_**\n\nThe encoding to be used when reading the file. The 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*   `null`\n\nUsing `null` explicitly will return the file as a [`Cypress.Buffer`](/llm/markdown/api/utilities/buffer.md) instance, regardless of file extension.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.readFile()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.readFile()` to resolve before [timing out](#Timeouts) |\n\n### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)\n\n*   `cy.readFile()` yields the contents of the file.\n*   The file will be read from disk again if any upcoming command (such as an assertion) in the chain fails.\n",
      "section": "api",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 245
    },
    {
      "id": "api/commands/readfile#arguments",
      "doc_id": "api/commands/readfile",
      "heading": "Arguments",
      "heading_level": 3,
      "content_markdown": "### Arguments\n\n**filePath _(String)_**\n\nA path to a file within the project root (the directory that contains the [Cypress configuration file](/llm/markdown/app/references/configuration.md)).\n\n**encoding _(String)_**\n\nThe encoding to be used when reading the file. The 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*   `null`\n\nUsing `null` explicitly will return the file as a [`Cypress.Buffer`](/llm/markdown/api/utilities/buffer.md) instance, regardless of file extension.\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.readFile()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.readFile()` to resolve before [timing out](#Timeouts) |\n",
      "section": "api",
      "anchors": [
        "arguments"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 177
    },
    {
      "id": "api/commands/readfile#yields-learn-about-subject-management",
      "doc_id": "api/commands/readfile",
      "heading": "Yields Learn about subject management",
      "heading_level": 3,
      "content_markdown": "### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)\n\n*   `cy.readFile()` yields the contents of the file.\n*   The file will be read from disk again if any upcoming command (such as an assertion) in the chain fails.\n",
      "section": "api",
      "anchors": [
        "yields-learn-about-subject-management"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 47
    },
    {
      "id": "api/commands/readfile#examples",
      "doc_id": "api/commands/readfile",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### Text\n\n#### Read a `.txt` file\n\nFor any file other than JSON, the contents of the file are returned.\n\n```\n// path/to/message.txtHello World\n```\n\n```\ncy.readFile('path/to/message.txt').should('eq', 'Hello World') // true\n```\n\n### JSON\n\nFor JSON, the contents yielded are parsed into JavaScript and returned.\n\n```\n// data.json{  \"name\": \"Eliza\",  \"email\": \"eliza@example.com\"}\n```\n\n```\ncy.readFile('path/to/data.json').its('name').should('eq', 'Eliza') // true\n```\n\n### YAML\n\n#### Get translation data from a YAML file\n\n```\nconst YAML = require('yamljs')cy.readFile('languages/en.yml').then((str) => {  // parse the string into object literal  const english = YAML.parse(str)  cy.get('#sidebar')    .find('.sidebar-title')    .each(($el, i) => {      englishTitle = english.sidebar[i]      expect($el.text()).to.eq(englishTitle)    })})\n```\n\n### Encoding\n\n#### Specify the encoding with the second argument\n\n```\ncy.readFile('path/to/logo.png', 'base64').then((logo) => {  // logo will be encoded as base64  // and should look something like this:  // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...})\n```\n\n#### Read\n\n```\ncy.fixture('path/to/logo.png', null).then((logo) => {  // logo will be read as a buffer  // and should look something like this:  // Buffer([0, 0, ...])})\n```\n\n### Playing MP3 file\n\n```\ncy.readFile('audio/sound.mp3', 'base64').then((mp3) => {  const uri = 'data:audio/mp3;base64,' + mp3  const audio = new Audio(uri)  audio.play()})\n```\n",
      "section": "api",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 243
    },
    {
      "id": "api/commands/readfile#text",
      "doc_id": "api/commands/readfile",
      "heading": "Text",
      "heading_level": 3,
      "content_markdown": "### Text\n\n#### Read a `.txt` file\n\nFor any file other than JSON, the contents of the file are returned.\n\n```\n// path/to/message.txtHello World\n```\n\n```\ncy.readFile('path/to/message.txt').should('eq', 'Hello World') // true\n```\n",
      "section": "api",
      "anchors": [
        "text"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 43
    },
    {
      "id": "api/commands/readfile#read-a-txt-file",
      "doc_id": "api/commands/readfile",
      "heading": "Read a .txt file",
      "heading_level": 4,
      "content_markdown": "#### Read a `.txt` file\n\nFor any file other than JSON, the contents of the file are returned.\n\n```\n// path/to/message.txtHello World\n```\n\n```\ncy.readFile('path/to/message.txt').should('eq', 'Hello World') // true\n```\n",
      "section": "api",
      "anchors": [
        "read-a-txt-file"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 40
    },
    {
      "id": "api/commands/readfile#yaml",
      "doc_id": "api/commands/readfile",
      "heading": "YAML",
      "heading_level": 3,
      "content_markdown": "### YAML\n\n#### Get translation data from a YAML file\n\n```\nconst YAML = require('yamljs')cy.readFile('languages/en.yml').then((str) => {  // parse the string into object literal  const english = YAML.parse(str)  cy.get('#sidebar')    .find('.sidebar-title')    .each(($el, i) => {      englishTitle = english.sidebar[i]      expect($el.text()).to.eq(englishTitle)    })})\n```\n",
      "section": "api",
      "anchors": [
        "yaml"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 53
    },
    {
      "id": "api/commands/readfile#get-translation-data-from-a-yaml-file",
      "doc_id": "api/commands/readfile",
      "heading": "Get translation data from a YAML file",
      "heading_level": 4,
      "content_markdown": "#### Get translation data from a YAML file\n\n```\nconst YAML = require('yamljs')cy.readFile('languages/en.yml').then((str) => {  // parse the string into object literal  const english = YAML.parse(str)  cy.get('#sidebar')    .find('.sidebar-title')    .each(($el, i) => {      englishTitle = english.sidebar[i]      expect($el.text()).to.eq(englishTitle)    })})\n```\n",
      "section": "api",
      "anchors": [
        "get-translation-data-from-a-yaml-file"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 51
    },
    {
      "id": "api/commands/readfile#encoding",
      "doc_id": "api/commands/readfile",
      "heading": "Encoding",
      "heading_level": 3,
      "content_markdown": "### Encoding\n\n#### Specify the encoding with the second argument\n\n```\ncy.readFile('path/to/logo.png', 'base64').then((logo) => {  // logo will be encoded as base64  // and should look something like this:  // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...})\n```\n\n#### Read\n\n```\ncy.fixture('path/to/logo.png', null).then((logo) => {  // logo will be read as a buffer  // and should look something like this:  // Buffer([0, 0, ...])})\n```\n",
      "section": "api",
      "anchors": [
        "encoding"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 79
    },
    {
      "id": "api/commands/readfile#specify-the-encoding-with-the-second-argument",
      "doc_id": "api/commands/readfile",
      "heading": "Specify the encoding with the second argument",
      "heading_level": 4,
      "content_markdown": "#### Specify the encoding with the second argument\n\n```\ncy.readFile('path/to/logo.png', 'base64').then((logo) => {  // logo will be encoded as base64  // and should look something like this:  // aIJKnwxydrB10NVWqhlmmC+ZiWs7otHotSAAAOw==...})\n```\n",
      "section": "api",
      "anchors": [
        "specify-the-encoding-with-the-second-argument"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 40
    },
    {
      "id": "api/commands/readfile#notes",
      "doc_id": "api/commands/readfile",
      "heading": "Notes",
      "heading_level": 2,
      "content_markdown": "## Notes\n\n### Existence\n\n#### Default file existence 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```\n// will fail after the defaultCommandTimeout is reachedcy.readFile('does-not-exist.yaml')\n```\n\n#### Asserting file non-existence\n\nYou can assert that a file does not exist like so:\n\n```\n// will pass if the file does not existcy.readFile('does-not-exist.yaml').should('not.exist')\n```\n\n#### Read a file that might not exist\n\n[See our example on using `cy.task()` to read a file that _may_ not exist.](/llm/markdown/api/commands/task.md#Read-a-file-that-might-not-exist)\n\n### Retries\n\n#### Automatic retries\n\n`cy.readFile()` will continue to read the file until it passes all of its assertions.\n\n```\n// if this assertion fails cy.readFile will poll the file// until it eventually passes its assertions (or times out)cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...')\n```\n\nStarting in Cypress `v13`, `cy.readFile()` is a query, and will continue to read the file until all chained commands of any type pass, not just assertions.\n\n```\n// will retry until the json file has a `users[123].name` field, and// the assertion passescy.readFile('users.json').its('users.123.name').should('eq', 'John Doe')\n```\n",
      "section": "api",
      "anchors": [
        "notes"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 257
    },
    {
      "id": "api/commands/readfile#existence",
      "doc_id": "api/commands/readfile",
      "heading": "Existence",
      "heading_level": 3,
      "content_markdown": "### Existence\n\n#### Default file existence 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```\n// will fail after the defaultCommandTimeout is reachedcy.readFile('does-not-exist.yaml')\n```\n\n#### Asserting file non-existence\n\nYou can assert that a file does not exist like so:\n\n```\n// will pass if the file does not existcy.readFile('does-not-exist.yaml').should('not.exist')\n```\n\n#### Read a file that might not exist\n\n[See our example on using `cy.task()` to read a file that _may_ not exist.](/llm/markdown/api/commands/task.md#Read-a-file-that-might-not-exist)\n",
      "section": "api",
      "anchors": [
        "existence"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 136
    },
    {
      "id": "api/commands/readfile#default-file-existence-assertion",
      "doc_id": "api/commands/readfile",
      "heading": "Default file existence assertion",
      "heading_level": 4,
      "content_markdown": "#### Default file existence 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```\n// will fail after the defaultCommandTimeout is reachedcy.readFile('does-not-exist.yaml')\n```\n",
      "section": "api",
      "anchors": [
        "default-file-existence-assertion"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 69
    },
    {
      "id": "api/commands/readfile#retries",
      "doc_id": "api/commands/readfile",
      "heading": "Retries",
      "heading_level": 3,
      "content_markdown": "### Retries\n\n#### Automatic retries\n\n`cy.readFile()` will continue to read the file until it passes all of its assertions.\n\n```\n// if this assertion fails cy.readFile will poll the file// until it eventually passes its assertions (or times out)cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...')\n```\n\nStarting in Cypress `v13`, `cy.readFile()` is a query, and will continue to read the file until all chained commands of any type pass, not just assertions.\n\n```\n// will retry until the json file has a `users[123].name` field, and// the assertion passescy.readFile('users.json').its('users.123.name').should('eq', 'John Doe')\n```\n",
      "section": "api",
      "anchors": [
        "retries"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 119
    },
    {
      "id": "api/commands/readfile#automatic-retries",
      "doc_id": "api/commands/readfile",
      "heading": "Automatic retries",
      "heading_level": 4,
      "content_markdown": "#### Automatic retries\n\n`cy.readFile()` will continue to read the file until it passes all of its assertions.\n\n```\n// if this assertion fails cy.readFile will poll the file// until it eventually passes its assertions (or times out)cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...')\n```\n\nStarting in Cypress `v13`, `cy.readFile()` is a query, and will continue to read the file until all chained commands of any type pass, not just assertions.\n\n```\n// will retry until the json file has a `users[123].name` field, and// the assertion passescy.readFile('users.json').its('users.123.name').should('eq', 'John Doe')\n```\n",
      "section": "api",
      "anchors": [
        "automatic-retries"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 116
    },
    {
      "id": "api/commands/readfile#rules",
      "doc_id": "api/commands/readfile",
      "heading": "Rules",
      "heading_level": 2,
      "content_markdown": "## Rules\n\n### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)\n\n*   `cy.readFile()` requires being chained off of `cy`.\n*   `cy.readFile()` requires the file must exist.\n*   `cy.readFile()` requires the file be successfully read from disk.\n\n### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)\n\n*   `cy.readFile()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed.\n\n### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)\n\n*   `cy.readFile()` can time out waiting for assertions you've added to pass.\n*   `cy.readFile()` can time out when the content being read takes a significant amount of time to encode.\n",
      "section": "api",
      "anchors": [
        "rules"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 112
    },
    {
      "id": "api/commands/readfile#requirements-learn-about-chaining-commands",
      "doc_id": "api/commands/readfile",
      "heading": "Requirements Learn about chaining commands",
      "heading_level": 3,
      "content_markdown": "### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)\n\n*   `cy.readFile()` requires being chained off of `cy`.\n*   `cy.readFile()` requires the file must exist.\n*   `cy.readFile()` requires the file be successfully read from disk.\n",
      "section": "api",
      "anchors": [
        "requirements-learn-about-chaining-commands"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 41
    },
    {
      "id": "api/commands/readfile#timeouts-learn-about-timeouts",
      "doc_id": "api/commands/readfile",
      "heading": "Timeouts Learn about timeouts",
      "heading_level": 3,
      "content_markdown": "### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)\n\n*   `cy.readFile()` can time out waiting for assertions you've added to pass.\n*   `cy.readFile()` can time out when the content being read takes a significant amount of time to encode.\n",
      "section": "api",
      "anchors": [
        "timeouts-learn-about-timeouts"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 47
    },
    {
      "id": "api/commands/readfile#command-log",
      "doc_id": "api/commands/readfile",
      "heading": "Command Log",
      "heading_level": 2,
      "content_markdown": "## Command Log\n\n**_List the contents of your package.json file_**\n\n```\ncy.readFile('package.json')\n```\n\nThe command above will display in the Command Log as:\n\nWhen clicking on the `readFile` command within the command log, the console outputs the following:\n",
      "section": "api",
      "anchors": [
        "command-log"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 51
    },
    {
      "id": "api/commands/readfile#history",
      "doc_id": "api/commands/readfile",
      "heading": "History",
      "heading_level": 2,
      "content_markdown": "## History\n\n| Version | Changes |\n| --- | --- |\n| [13.0.0](/llm/markdown/app/references/changelog.md#13-0-0) | `cy.readFile()` became a query |\n| [9.0.0](/llm/markdown/app/references/changelog.md#9-0-0) | Changed `null` encoding to read as Buffer |\n| [0.17.2](/llm/markdown/app/references/changelog.md#0-17-2) | Improved error messaging |\n| [0.17.1](/llm/markdown/app/references/changelog.md#0-17-1) | `cy.readFile()` command added |\n",
      "section": "api",
      "anchors": [
        "history"
      ],
      "path": "/llm/json/chunked/api/commands/readfile.json",
      "token_estimate": 60
    }
  ]
}