fix: Adding an existing command with Cypress.Commands.add() will th…

…row an error (#18587)

Co-authored-by: Chris Breiding <chrisbreiding@users.noreply.github.com>
Co-authored-by: Jennifer Shehane <jennifer@cypress.io>

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

@@ -81,6 +81,21 @@ describe('src/cy/commands/commands', () => {
         expect($ce.get(0)).to.eq(ce.get(0))
       })
     })
+
+    it('throws when attempting to add an existing command', (done) => {
+      cy.on('fail', (err) => {
+        expect(err.message).to.eq('`Cypress.Commands.add()` is used to create new commands, but `get` is an existing Cypress command.\n\nPlease use `Cypress.Commands.overwrite()` if you would like to overwrite an existing command.\n')
+        expect(err.docsUrl).to.eq('https://on.cypress.io/custom-commands')
+
+        done()
+      })
+
+      Cypress.Commands.add('get', () => {
+        cy
+        .get('[contenteditable]')
+        .first()
+      })
+    })
   })
 
   context('errors', () => {

packages/driver/src/cypress/commands.ts

@@ -3,6 +3,7 @@
 import _ from 'lodash'
 
 import $errUtils from './error_utils'
+import $stackUtils from './stack_utils'
 
 import { allCommands } from '../cy/commands'
 import { addCommand } from '../cy/net-stubbing'
@@ -30,6 +31,10 @@ export default {
     // of commands
     const commands = {}
     const commandBackups = {}
+    // we track built in commands to ensure users cannot
+    // add custom commands with the same name
+    const builtInCommandNames = {}
+    let addingBuiltIns
 
     const store = (obj) => {
       commands[obj.name] = obj
@@ -126,6 +131,24 @@ export default {
       },
 
       add (name, options, fn) {
+        if (builtInCommandNames[name]) {
+          $errUtils.throwErrByPath('miscellaneous.invalid_new_command', {
+            args: {
+              name,
+            },
+            stack: (new state('specWindow').Error('add command stack')).stack,
+            errProps: {
+              appendToStack: {
+                title: 'From Cypress Internals',
+                content: $stackUtils.stackWithoutMessage((new Error('add command internal stack')).stack),
+              } },
+          })
+        }
+
+        if (addingBuiltIns) {
+          builtInCommandNames[name] = true
+        }
+
         if (_.isFunction(options)) {
           fn = options
           options = {}
@@ -163,12 +186,14 @@ export default {
       },
     }
 
+    addingBuiltIns = true
     // perf loop
     for (let cmd of builtInCommands) {
       // support "export default" syntax
       cmd = cmd.default || cmd
       cmd(Commands, Cypress, cy, state, config)
     }
+    addingBuiltIns = false
 
     return Commands
   },

packages/driver/src/cypress/error_messages.ts

@@ -803,6 +803,10 @@ export default {
       message: 'Could not find a command for: `{{name}}`.\n\nAvailable commands are: {{cmds}}.\n',
       docsUrl: 'https://on.cypress.io/api',
     },
+    invalid_new_command: {
+      message: '`Cypress.Commands.add()` is used to create new commands, but `{{name}}` is an existing Cypress command.\n\nPlease use `Cypress.Commands.overwrite()` if you would like to overwrite an existing command.\n',
+      docsUrl: 'https://on.cypress.io/custom-commands',
+    },
     invalid_overwrite: {
       message: 'Cannot overwite command for: `{{name}}`. An existing command does not exist by that name.',
       docsUrl: 'https://on.cypress.io/api',

packages/driver/src/cypress/error_utils.ts

@@ -230,8 +230,10 @@ const throwErr = (err, options = {}) => {
 const throwErrByPath = (errPath, options = {}) => {
   const err = errByPath(errPath, options.args)
 
-  // gets rid of internal stack lines that just build the error
-  if (Error.captureStackTrace) {
+  if (options.stack) {
+    err.stack = $stackUtils.replacedStack(err, options.stack)
+  } else if (Error.captureStackTrace) {
+    // gets rid of internal stack lines that just build the error
     Error.captureStackTrace(err, throwErrByPath)
   }