feat(config): introduce deprecation warning handler, fix #1672 (#1700)

Allow passing custom handler for deprecation warnings allowing
fine-grained control how these are reported to a user

Author: xanf

docs/api/config.md

@@ -19,6 +19,29 @@ import { config } from '@vue/test-utils'
 config.showDeprecationWarnings = false
 ```
 
+### `deprecationWarningHandler`
+
+- type: `Function`
+
+Allows fine-grained control on deprecation warnings. When `showDeprecationWarnings` is set to `true`, all deprecation warnings will be passed to this handler with method name as first argument and original message as second.
+
+::: tip
+This could be useful to log deprecation messages to separate location or to help in gradual upgrade of codebase to latest version of test utils by ignoring certain deprecated functions warnings
+:::
+
+Example:
+
+```js
+import { config } from '@vue/test-utils'
+
+config.showDeprecationWarnings = true
+config.deprecationWarningHandler = (method, message) => {
+  if (method === 'emittedByOrder') return
+
+  console.error(msg)
+}
+```
+
 ### `stubs`
 
 - type: `{ [name: string]: Component | boolean | string }`

packages/shared/util.js

@@ -105,5 +105,9 @@ export function warnDeprecated(method: string, fallback: string = '') {
   if (!config.showDeprecationWarnings) return
   let msg = `${method} is deprecated and will be removed in the next major version.`
   if (fallback) msg += ` ${fallback}.`
-  warn(msg)
+  if (config.deprecationWarningHandler) {
+    config.deprecationWarningHandler(method, msg)
+  } else {
+    warn(msg)
+  }
 }

packages/test-utils/types/index.d.ts

@@ -166,6 +166,7 @@ interface VueTestUtilsConfigOptions {
   provide?: Record<string, any>,
   silent?: Boolean,
   showDeprecationWarnings?: boolean
+  deprecationWarningHandler?: Function
 }
 
 export declare function createLocalVue (): typeof Vue

test/specs/config.spec.js

@@ -19,6 +19,7 @@ describeWithShallowAndMount('config', mountingMethod => {
     config.stubs = configStubsSave
     config.silent = configSilentSave
     config.methods = {}
+    config.deprecationWarningHandler = null
     console.error = consoleErrorSave
   })
 
@@ -103,6 +104,17 @@ describeWithShallowAndMount('config', mountingMethod => {
     expect(wrapper.find('[data-testid="expanded"]').exists()).toEqual(false)
   })
 
+  it('invokes custom deprecation warning handler if specified in config', () => {
+    config.showDeprecationWarnings = true
+    config.deprecationWarningHandler = jest.fn()
+
+    const TestComponent = { template: `<div>Test</div>` }
+    mountingMethod(TestComponent, { attachToDocument: true })
+
+    expect(config.deprecationWarningHandler).toHaveBeenCalledTimes(1)
+    expect(console.error).not.toHaveBeenCalled()
+  })
+
   it('allows control deprecation warnings visibility for name method', () => {
     config.showDeprecationWarnings = true
     const Component = {