refactor: improve migration path for setMethods and options.methods

Author: afontcu

docs/api/wrapper-array/setMethods.md

@@ -2,6 +2,10 @@
 
 ::: warning Deprecation warning
 `setMethods` is deprecated and will be removed in future releases.
+
+There's no clear path to replace `setMethods`, because it really depends on your previous usage. It easily leads to flaky tests that rely on implementation details, which [is discouraged](<(https://github.com/vuejs/rfcs/blob/668866fa71d70322f6a7689e88554ab27d349f9c/active-rfcs/0000-vtu-api.md#setmethods)>).
+
+Thus, we suggest to to rethink those tests using the tools Vue Test Utils provides.
 :::
 
 Sets `Wrapper` `vm` methods and forces update on each `Wrapper` in `WrapperArray`.

docs/api/wrapper/setMethods.md

@@ -2,6 +2,10 @@
 
 ::: warning Deprecation warning
 `setMethods` is deprecated and will be removed in future releases.
+
+There's no clear path to replace `setMethods`, because it really depends on your previous usage. It easily leads to flaky tests that rely on implementation details, which [is discouraged](<(https://github.com/vuejs/rfcs/blob/668866fa71d70322f6a7689e88554ab27d349f9c/active-rfcs/0000-vtu-api.md#setmethods)>).
+
+Thus, we suggest to to rethink those tests using the tools Vue Test Utils provides.
 :::
 
 Sets `Wrapper` `vm` methods and forces update.

packages/shared/merge-options.js

@@ -35,7 +35,10 @@ export function mergeOptions(
     [key: string]: Function
   })
   if (methods && Object.keys(methods).length) {
-    warnDeprecated('overwriting methods via the `methods` property')
+    warnDeprecated(
+      'overwriting methods via the `methods` property',
+      'There is no clear migration path for the `methods` property - Vue does not support arbitrarily replacement of methods, nor should VTU. If you need to stub out a method, extract it out and test it. Otherwise, the suggestion is to rethink those tests'
+    )
   }
 
   const provide = (getOption(options.provide, config.provide): Object)

packages/test-utils/src/wrapper.js

@@ -632,7 +632,10 @@ export default class Wrapper implements BaseWrapper {
    * @deprecated
    */
   setMethods(methods: Object): void {
-    warnDeprecated(`setMethods`)
+    warnDeprecated(
+      `setMethods`,
+      `There is no clear migration path for setMethods - Vue does not support arbitrarily replacement of methods, nor should VTU. If you need to stub out a method, extract it out and test it. Otherwise, the suggestion is to rethink those tests`
+    )
 
     if (!this.vm) {
       throwError(`wrapper.setMethods() can only be called on a Vue instance`)

test/specs/config.spec.js

@@ -144,4 +144,58 @@ describeWithShallowAndMount('config', mountingMethod => {
       )
     })
   })
+
+  describe('methods overriding deprecation warning', () => {
+    const expectedErrorMessage = `There is no clear migration path`
+    const Component = {
+      template: '<div></div>',
+      methods: {
+        foo() {}
+      }
+    }
+
+    it('should show warning for options.methods if config is enabled', () => {
+      config.showDeprecationWarnings = true
+
+      mountingMethod(Component, {
+        methods: { foo: () => {} }
+      })
+
+      expect(console.error).to.be.calledWith(
+        sandbox.match(expectedErrorMessage)
+      )
+    })
+
+    it('should not show warning for options.methods if config is disabled', () => {
+      config.showDeprecationWarnings = false
+
+      mountingMethod(Component, {
+        methods: { foo: () => {} }
+      })
+
+      expect(console.error).not.to.be.calledWith(
+        sandbox.match(expectedErrorMessage)
+      )
+    })
+
+    it('should show warning for setMethods if config is enabled', () => {
+      config.showDeprecationWarnings = true
+
+      mountingMethod(Component).setMethods({ foo: () => {} })
+
+      expect(console.error).to.be.calledWith(
+        sandbox.match(expectedErrorMessage)
+      )
+    })
+
+    it('should not show warning for setMethods if config is disabled', () => {
+      config.showDeprecationWarnings = false
+
+      mountingMethod(Component).setMethods({ foo: () => {} })
+
+      expect(console.error).not.to.be.calledWith(
+        sandbox.match(expectedErrorMessage)
+      )
+    })
+  })
 })