Adding readFile/writeFile doc around new timeout features (#4244)

Author: tbiethman

content/_changelogs/9.1.0.md

@@ -23,5 +23,5 @@ _Released 11/22/2021_
 - The warning message for retrying connection to a browser has been improved to
   indicate when it is still waiting. Fixes
   [#18644](https://github.com/cypress-io/cypress/issues/18644).
- - Cypress commands that rely on `this` context now have access to `this` when 
-   overridden. Fixes [#18899](https://github.com/cypress-io/cypress/pull/18899).
+- Cypress commands that rely on `this` context now have access to `this` when
+  overridden. Fixes [#18899](https://github.com/cypress-io/cypress/pull/18899).

content/api/commands/readfile.md

@@ -46,7 +46,8 @@ supported:
 - `'utf-16le'`
 - `null`
 
-Using `null` explicitly will return the file as a `Buffer`, regardless of file extension.
+Using `null` explicitly will return the file as a `Buffer`, regardless of file
+extension.
 
 **<Icon name="angle-right"></Icon> options** **_(Object)_**
 
@@ -59,7 +60,7 @@ Pass in an options object to change the default behavior of `cy.readFile()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.readFile()` yields the contents of the file.</li></List>
+- `cy.readFile()` yields the contents of the file.
 
 ## Examples
 
@@ -195,21 +196,21 @@ cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...')
 
 ### Requirements [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands)
 
-<List><li>`cy.readFile()` requires being chained off of
-`cy`.</li><li>`cy.readFile()` requires the file must
-exist.</li><li>`cy.readFile()` requires the file be successfully read from
-disk.</li></List>
+- `cy.readFile()` requires being chained off of `cy`.
+- `cy.readFile()` requires the file must exist.
+- `cy.readFile()` requires the file be successfully read from disk.
 
 ### Assertions [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Assertions)
 
-<List><li>`cy.readFile()` will automatically
-[retry](/guides/core-concepts/retry-ability) until all chained assertions have
-passed</li></List>
+- `cy.readFile()` will automatically
+  [retry](/guides/core-concepts/retry-ability) until all chained assertions have
+  passed.
 
 ### Timeouts [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Timeouts)
 
-<List><li>`cy.readFile()` can time out waiting for assertions you've added to
-pass.</li></List>
+- `cy.readFile()` can time out waiting for assertions you've added to pass.
+- `cy.readFile()` can time out when the content being read takes a significant
+  amount of time to encode.
 
 ## Command Log
 
@@ -228,6 +229,14 @@ outputs the following:
 
 <DocsImage src="/img/api/readfile/console-log-shows-content-from-file-formatted-as-javascript.png" alt="Console Log readFile" ></DocsImage>
 
+## History
+
+| Version                                       | Changes                                   |
+| --------------------------------------------- | ----------------------------------------- |
+| [9.0.0](/guides/references/changelog#9-0-0)   | Changed `null` encoding to read as Buffer |
+| [0.17.2](/guides/references/changelog#0-17-2) | Improved error messaging                  |
+| [0.17.1](/guides/references/changelog#0-17-1) | `cy.readFile()` command added             |
+
 ## See also
 
 - [`cy.exec()`](/api/commands/exec)

content/api/commands/writefile.md

@@ -28,7 +28,8 @@ cy.writeFile('menu.json')
 A path to a file within the project root (the directory that contains the
 default `cypress.json`).
 
-**<Icon name="angle-right"></Icon> contents** **_(String, Array, Object or Buffer)_**
+**<Icon name="angle-right"></Icon> contents** **_(String, Array, Object or
+Buffer)_**
 
 The contents to be written to the file.
 
@@ -57,11 +58,12 @@ first encoding it as a string.
 
 Pass in an options object to change the default behavior of `cy.writeFile()`.
 
-| Option     | Default | Description                                                                                         |
-| ---------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `log`      | `true`  | Displays the command in the [Command log](/guides/core-concepts/test-runner#Command-Log)            |
-| `flag`     | `w`     | File system flag as used with [`fs.writeFile`](https://nodejs.org/api/fs.html#fs_file_system_flags) |
-| `encoding` | `utf8`  | The encoding to be used when writing to the file                                                    |
+| Option     | Default                                                              | Description                                                                                         |
+| ---------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `log`      | `true`                                                               | Displays the command in the [Command log](/guides/core-concepts/test-runner#Command-Log)            |
+| `flag`     | `w`                                                                  | File system flag as used with [`fs.writeFile`](https://nodejs.org/api/fs.html#fs_file_system_flags) |
+| `encoding` | `utf8`                                                               | The encoding to be used when writing to the file                                                    |
+| `timeout`  | [`defaultCommandTimeout`](/guides/references/configuration#Timeouts) | Time to wait for `.writeFile()` to resolve before [timing out](#Timeouts)                           |
 
 <Alert type="info">
 
@@ -73,8 +75,7 @@ parameter and include encoding there. This is the same behavior as
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.writeFile()` yields the value of the <code>contents</code>
-argument.</li></List>
+- `cy.writeFile()` yields `null`.
 
 ## Examples
 
@@ -193,6 +194,7 @@ cy.readFile(filename).then((list) => {
 ### Buffer
 
 #### Write a buffer directly without encoding as a string
+
 ```javascript
 const filename = '/path/to/file.png'
 
@@ -207,7 +209,6 @@ cy.readFile(filename, null).then((obj) => {
 ### Requirements [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands)
 
 - `cy.writeFile()` requires being chained off of `cy`.
-
 - `cy.writeFile()` requires the file be successfully written to disk. Anything
   preventing this such as OS permission issues will cause it to fail.
 
@@ -218,15 +219,8 @@ cy.readFile(filename, null).then((obj) => {
 
 ### Timeouts [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Timeouts)
 
-- `cy.writeFile()` should never time out.
-
-<Alert type="warning">
-
-Because `cy.writeFile()` is asynchronous it is technically possible for there to
-be a timeout while talking to the internal Cypress automation APIs. But for
-practical purposes it should never happen.
-
-</Alert>
+- `cy.writeFile()` can time out when the content being written takes a
+  significant amount of time to encode.
 
 ## Command Log
 
@@ -249,6 +243,7 @@ outputs the following:
 
 | Version                                     | Changes                                                  |
 | ------------------------------------------- | -------------------------------------------------------- |
+| [9.2.0](/guides/references/changelog#9-2-0) | Added `timeout` option                                   |
 | [4.0.0](/guides/references/changelog#4-0-0) | `cy.writeFile()` now yields `null` instead of `contents` |
 | [3.1.1](/guides/references/changelog#3-1-1) | Added `flag` option and appending with `a+`              |
 | [1.0.0](/guides/references/changelog#1.0.0) | `cy.writeFile()` command added                           |