How do I deprecate a feature in my addon?

Question

I am writing an Ember.js Addon, and I need to deprecate a feature. Can I use the same deprecation system that Ember uses? I want my users to be able to silence the warnings.

Ideally, I also need to be able to test that the deprecation message works under the right conditions, from within my test suite.

I'm using Ember 3.x.

Answer 1

An addon can use the same style of deprecation warnings as Ember uses, through the deprecate method:

import { deprecate } from '@ember/application/deprecations';

deprecate takes three arguments: the string as a message, a boolean test where falsey means the deprecation will be shown, and an options object with more information to be displayed.

For example:

import { deprecate } from '@ember/application/deprecations';
// ...
deprecate(
   "message about your addon that mentions the addon by name", 
   false,
   {
      id: 'send-component-hash',
      until: '2.0.0',
      url: 'some url goes here'
    }
);
// ...

The message in the console will look something like this:

Testing a deprecation can be done with a library like ember-qunit-assert. Once it is installed, expectDeprecation will be available on assert if you are already using qunit in your tests:

assert.expectDeprecation(/expected deprecation message/);