feat: Allow explicit null encoding for readFile/writeFile

cli/types/cypress.d.ts

@@ -5677,7 +5677,7 @@ declare namespace Cypress {
     xhr: XMLHttpRequest
   }
 
-  type Encodings = 'ascii' | 'base64' | 'binary' | 'hex' | 'latin1' | 'utf8' | 'utf-8' | 'ucs2' | 'ucs-2' | 'utf16le' | 'utf-16le'
+  type Encodings = 'ascii' | 'base64' | 'binary' | 'hex' | 'latin1' | 'utf8' | 'utf-8' | 'ucs2' | 'ucs-2' | 'utf16le' | 'utf-16le' | null
   type PositionType = 'topLeft' | 'top' | 'topRight' | 'left' | 'center' | 'right' | 'bottomLeft' | 'bottom' | 'bottomRight'
   type ViewportPreset = 'macbook-16' | 'macbook-15' | 'macbook-13' | 'macbook-11' | 'ipad-2' | 'ipad-mini' | 'iphone-xr' | 'iphone-x' | 'iphone-6+' | 'iphone-se2' | 'iphone-8' | 'iphone-7' | 'iphone-6' | 'iphone-5' | 'iphone-4' | 'iphone-3' | 'samsung-s10' | 'samsung-note9'
   interface Offset {

packages/driver/cypress/integration/commands/files_spec.js

@@ -37,6 +37,22 @@ describe('src/cy/commands/files', () => {
       })
     })
 
+    // https://github.com/cypress-io/cypress/issues/1558
+    it('passes explicit null encoding through to server and decodes response', () => {
+      Cypress.backend.resolves({
+        contents: Buffer.from('\n'),
+        filePath: '/path/to/foo.json',
+      })
+
+      cy.readFile('foo.json', null).then(() => {
+        expect(Cypress.backend).to.be.calledWith(
+          'read:file',
+          'foo.json',
+          { encoding: null },
+        )
+      }).should('eql', Buffer.from('\n'))
+    })
+
     it('sets the contents as the subject', () => {
       Cypress.backend.resolves(okResponse)
 
@@ -340,6 +356,23 @@ describe('src/cy/commands/files', () => {
       })
     })
 
+    // https://github.com/cypress-io/cypress/issues/1558
+    it('explicit null encoding is sent to server as Buffer', () => {
+      Cypress.backend.resolves(okResponse)
+
+      cy.writeFile('foo.txt', Buffer.from([0, 0, 54, 255]), null).then(() => {
+        expect(Cypress.backend).to.be.calledWith(
+          'write:file',
+          'foo.txt',
+          Buffer.from([0, 0, 54, 255]),
+          {
+            encoding: null,
+            flag: 'w',
+          },
+        )
+      })
+    })
+
     it('can take encoding as part of options', () => {
       Cypress.backend.resolves(okResponse)
 

packages/driver/cypress/integration/commands/fixtures_spec.js

@@ -35,6 +35,17 @@ describe('src/cy/commands/fixtures', () => {
       })
     })
 
+    // https://github.com/cypress-io/cypress/issues/1558
+    it('passes explicit null encoding through to server and decodes response', () => {
+      Cypress.backend.withArgs('get:fixture').resolves(Buffer.from('\n'))
+
+      cy.fixture('foo', null).then((obj) => {
+        expect(Cypress.backend).to.be.calledWith('get:fixture', 'foo', {
+          encoding: null,
+        })
+      }).should('eql', Buffer.from('\n'))
+    })
+
     it('can have encoding as second argument and options as third argument', () => {
       Cypress.backend.withArgs('get:fixture').resolves({ foo: 'bar' })
 

packages/driver/src/cy/commands/files.ts

@@ -11,11 +11,16 @@ export default (Commands, Cypress, cy) => {
 
       if (_.isObject(encoding)) {
         userOptions = encoding
-        encoding = null
+        encoding = undefined
       }
 
       options = _.defaults({}, userOptions, {
-        encoding: encoding != null ? encoding : 'utf8',
+        // https://github.com/cypress-io/cypress/issues/1558
+        // If no encoding is specified, then Cypress has historically defaulted
+        // to `utf8`, because of it's focus on text files. This is in contrast to
+        // NodeJs, which defaults to binary. We allow users to pass in `null`
+        // to restore the default node behavior.
+        encoding: encoding === undefined ? 'utf8' : encoding,
         log: true,
       })
 
@@ -53,6 +58,14 @@ export default (Commands, Cypress, cy) => {
             args: { cmd: 'readFile', action: 'read', file, filePath: err.filePath, error: err.message },
           })
         }).then(({ contents, filePath }) => {
+          // https://github.com/cypress-io/cypress/issues/1558
+          // We invoke Buffer.from() in order to transform this from an ArrayBuffer -
+          // which socket.io uses to transfer the file over the websocket - into a
+          // `Buffer`, which webpack polyfills in the browser.
+          if (options.encoding === null) {
+            contents = Buffer.from(contents)
+          }
+
           consoleProps['File Path'] = filePath
           consoleProps['Contents'] = contents
 
@@ -85,11 +98,16 @@ export default (Commands, Cypress, cy) => {
 
       if (_.isObject(encoding)) {
         userOptions = encoding
-        encoding = null
+        encoding = undefined
       }
 
       options = _.defaults({}, userOptions, {
-        encoding: encoding ? encoding : 'utf8',
+        // https://github.com/cypress-io/cypress/issues/1558
+        // If no encoding is specified, then Cypress has historically defaulted
+        // to `utf8`, because of it's focus on text files. This is in contrast to
+        // NodeJs, which defaults to binary. We allow users to pass in `null`
+        // to restore the default node behavior.
+        encoding: encoding === undefined ? 'utf8' : encoding,
         flag: userOptions.flag ? userOptions.flag : 'w',
         log: true,
       })
@@ -120,7 +138,7 @@ export default (Commands, Cypress, cy) => {
         })
       }
 
-      if (_.isObject(contents)) {
+      if (_.isObject(contents) && !Buffer.isBuffer(contents)) {
         contents = JSON.stringify(contents, null, 2)
       }
 

packages/driver/src/cy/commands/fixtures.ts

@@ -6,6 +6,10 @@ import Promise from 'bluebird'
 import $errUtils from '../../cypress/error_utils'
 
 const clone = (obj) => {
+  if (Buffer.isBuffer(obj)) {
+    return Buffer.from(obj)
+  }
+
   return JSON.parse(JSON.stringify(obj))
 }
 
@@ -47,7 +51,7 @@ export default (Commands, Cypress, cy, state, config) => {
         options = args[1]
       }
 
-      if (_.isString(args[0])) {
+      if (_.isString(args[0]) || args[0] === null) {
         options.encoding = args[0]
       }
 
@@ -64,6 +68,18 @@ export default (Commands, Cypress, cy, state, config) => {
           return $errUtils.throwErr(response.__error)
         }
 
+        // https://github.com/cypress-io/cypress/issues/1558
+        // We invoke Buffer.from() in order to transform this from an ArrayBuffer -
+        // which socket.io uses to transfer the file over the websocket - into a
+        // `Buffer`, which webpack polyfills in the browser.
+        if (options.encoding === null) {
+          response = Buffer.from(response)
+        } else if (response instanceof ArrayBuffer) {
+          // Cypress' behavior is to base64 encode binary files if the user
+          // doesn't explicitly pass `null` as the encoding.
+          response = Buffer.from(response).toString('base64')
+        }
+
         // add the fixture to the cache
         // so it can just be returned next time
         cache[fixture] = response

packages/net-stubbing/lib/server/util.ts

@@ -120,7 +120,7 @@ export async function setResponseFromFixture (getFixtureFn: GetFixtureFn, static
     return
   }
 
-  const data = await getFixtureFn(fixture.filePath, { encoding: fixture.encoding || null })
+  const data = await getFixtureFn(fixture.filePath, { encoding: fixture.encoding })
 
   const { headers } = staticResponse
 

packages/server/lib/files.js

@@ -4,9 +4,14 @@ const { fs } = require('./util/fs')
 module.exports = {
   readFile (projectRoot, file, options = {}) {
     const filePath = path.resolve(projectRoot, file)
-    const readFn = path.extname(filePath) === '.json' ? fs.readJsonAsync : fs.readFileAsync
+    const readFn = (path.extname(filePath) === '.json' && options.encoding !== null) ? fs.readJsonAsync : fs.readFileAsync
 
-    return readFn(filePath, options.encoding || 'utf8')
+    // https://github.com/cypress-io/cypress/issues/1558
+    // If no encoding is specified, then Cypress has historically defaulted
+    // to `utf8`, because of it's focus on text files. This is in contrast to
+    // NodeJs, which defaults to binary. We allow users to pass in `null`
+    // to restore the default node behavior.
+    return readFn(filePath, options.encoding === undefined ? 'utf8' : options.encoding)
     .then((contents) => {
       return {
         contents,
@@ -22,7 +27,7 @@ module.exports = {
   writeFile (projectRoot, file, contents, options = {}) {
     const filePath = path.resolve(projectRoot, file)
     const writeOptions = {
-      encoding: options.encoding || 'utf8',
+      encoding: options.encoding === undefined ? 'utf8' : options.encoding,
       flag: options.flag || 'w',
     }
 

packages/server/lib/fixture.js

@@ -1,4 +1,3 @@
-const _ = require('lodash')
 const path = require('path')
 const check = require('syntax-error')
 const debug = require('debug')('cypress:server:fixture')
@@ -116,15 +115,24 @@ module.exports = {
   },
 
   parseFileByExtension (p, fixture, ext, options = {}) {
+    // https://github.com/cypress-io/cypress/issues/1558
+    // If the user explicitly specifies `null` as the encoding, we treat the
+    // file as binary regardless of extension. We base64 encode them for
+    // transmission over the websocket. There is a matching Buffer.from()
+    // in packages/driver/src/cy/commands/fixtures.ts
+    if (options.encoding === null) {
+      return this.parse(p, fixture)
+    }
+
     switch (ext) {
       case '.json': return this.parseJson(p, fixture)
       case '.js': return this.parseJs(p, fixture)
       case '.coffee': return this.parseCoffee(p, fixture)
       case '.html': return this.parseHtml(p, fixture)
       case '.png': case '.jpg': case '.jpeg': case '.gif': case '.tif': case '.tiff': case '.zip':
-        return this.parse(p, fixture, _.isNull(options.encoding) ? null : (options.encoding || 'base64'))
+        return this.parse(p, fixture, options.encoding)
       default:
-        return this.parse(p, fixture, _.isNull(options.encoding) ? null : options.encoding)
+        return this.parse(p, fixture, options.encoding || 'utf8')
     }
   },
 
@@ -184,7 +192,7 @@ module.exports = {
     .bind(this)
   },
 
-  parse (p, fixture, encoding = 'utf8') {
+  parse (p, fixture, encoding) {
     return fs.readFileAsync(p, encoding)
     .bind(this)
   },

packages/server/test/unit/files_spec.js

@@ -41,6 +41,13 @@ describe('lib/files', () => {
       })
     })
 
+    // https://github.com/cypress-io/cypress/issues/1558
+    it('explicit null encoding is sent to driver as a Buffer', function () {
+      return files.readFile(this.projectRoot, 'tests/_fixtures/ascii.foo', { encoding: null }).then(({ contents }) => {
+        expect(contents).to.eql(Buffer.from('\n'))
+      })
+    })
+
     it('parses json to valid JS object', function () {
       return files.readFile(this.projectRoot, 'tests/_fixtures/users.json').then(({ contents }) => {
         expect(contents).to.eql([
@@ -75,6 +82,15 @@ describe('lib/files', () => {
       })
     })
 
+    // https://github.com/cypress-io/cypress/issues/1558
+    it('explicit null encoding is written exactly as received', function () {
+      return files.writeFile(this.projectRoot, '.projects/write_file.txt', Buffer.from(''), { encoding: null }).then(() => {
+        return files.readFile(this.projectRoot, '.projects/write_file.txt', { encoding: null }).then(({ contents }) => {
+          expect(contents).to.eql(Buffer.from(''))
+        })
+      })
+    })
+
     it('overwrites existing file by default', function () {
       return files.writeFile(this.projectRoot, '.projects/write_file.txt', 'foo').then(() => {
         return files.readFile(this.projectRoot, '.projects/write_file.txt').then(({ contents }) => {