chore: deprecate Cypress.Cookies.preserveOnce and Cypress.Cookies.defaults (#21455)

cli/types/cypress.d.ts

@@ -482,7 +482,15 @@ declare namespace Cypress {
      */
     Cookies: {
       debug(enabled: boolean, options?: Partial<DebugOptions>): void
+      /**
+       * @deprecated Use `cy.session()` instead.
+       * @see https://on.cypress.io/session
+       */
       preserveOnce(...names: string[]): void
+      /**
+       * @deprecated Use `cy.session()` instead.
+       * @see https://on.cypress.io/session
+       */
       defaults(options: Partial<CookieDefaults>): CookieDefaults
     }
 

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

@@ -1254,7 +1254,7 @@ describe('src/cy/commands/cookies', () => {
     })
   })
 
-  context('Cypress.cookies.defaults', () => {
+  context('Cypress.Cookies.defaults', () => {
     it('throws error on use of renamed whitelist option', (done) => {
       cy.on('fail', (err) => {
         expect(err.message).to.include('`Cypress.Cookies.defaults` `whitelist` option has been renamed to `preserve`. Please rename `whitelist` to `preserve`.')
@@ -1266,5 +1266,21 @@ describe('src/cy/commands/cookies', () => {
         whitelist: 'session_id',
       })
     })
+
+    it('logs deprecation warning', () => {
+      cy.stub(Cypress.utils, 'warning')
+
+      Cypress.Cookies.defaults({})
+      expect(Cypress.utils.warning).to.be.calledWith('`Cypress.Cookies.defaults()` has been deprecated and will be removed in a future release. Consider using `cy.session()` instead.\n\nhttps://on.cypress.io/session')
+    })
+  })
+
+  context('Cypress.Cookies.preserveOnce', () => {
+    it('logs deprecation warning', () => {
+      cy.stub(Cypress.utils, 'warning')
+
+      Cypress.Cookies.preserveOnce({})
+      expect(Cypress.utils.warning).to.be.calledWith('`Cypress.Cookies.preserveOnce()` has been deprecated and will be removed in a future release. Consider using `cy.session()` instead.\n\nhttps://on.cypress.io/session')
+    })
   })
 })

packages/driver/cypress/integration/e2e/origin/cypress_api.spec.ts

@@ -234,8 +234,7 @@ describe('cy.origin Cypress API', () => {
       })
 
       cy.origin('http://foobar.com:3500', () => {
-        // @ts-ignore
-        Cypress.Cookies.preserveOnce({})
+        Cypress.Cookies.preserveOnce('')
       })
     })
 

packages/driver/src/cypress/cookies.ts

@@ -119,6 +119,8 @@ export const $Cookies = (namespace, domain) => {
     },
 
     preserveOnce (...keys) {
+      $errUtils.warnByPath('cookies.deprecated', { args: { cmd: 'Cypress.Cookies.preserveOnce' } })
+
       return _.each(keys, (key) => {
         return preserved[key] = true
       })
@@ -140,6 +142,7 @@ export const $Cookies = (namespace, domain) => {
     },
 
     defaults (obj = {}) {
+      $errUtils.warnByPath('cookies.deprecated', { args: { cmd: 'Cypress.Cookies.defaults' } })
       warnOnWhitelistRenamed(obj, 'Cypress.Cookies.defaults')
 
       // merge obj into defaults

packages/driver/src/cypress/error_messages.ts

@@ -309,7 +309,12 @@ export default {
         docsUrl: `https://on.cypress.io/${_.toLower(obj.cmd)}`,
       }
     },
-
+    deprecated (obj) {
+      return {
+        message: `${cmd(obj.cmd)} has been deprecated and will be removed in a future release. Consider using ${cmd('session')} instead.`,
+        docsUrl: 'https://on.cypress.io/session',
+      }
+    },
     invalid_name (obj) {
       return {
         message: `${cmd('{{cmd}}')} must be passed an RFC-6265-compliant cookie name. You passed:\n\n\`{{name}}\``,