diff --git a/addon/src/-private/finders.js b/addon/src/-private/finders.js index 98046778..8b2b011b 100644 --- a/addon/src/-private/finders.js +++ b/addon/src/-private/finders.js @@ -1,3 +1,4 @@ +import deprecate from './deprecate'; import { $, buildSelector, findClosestValue, guardMultiple } from './helpers'; import { getAdapter } from '../adapters/index'; import { throwBetterError, ELEMENT_NOT_FOUND } from './better-errors'; @@ -53,6 +54,13 @@ export function findElementWithAssert( targetSelector, options = {} ) { + deprecate( + 'find-element', + '`findElementWithAssert(` is deprecated. Please, consider using the `findOne(` instead.', + '2.2.0', + '3.0.0' + ); + const selector = buildSelector(pageObjectNode, targetSelector, options); const container = getContainer(pageObjectNode, options); @@ -74,6 +82,13 @@ export function findElementWithAssert( * @deprecated */ export function findElement(pageObjectNode, targetSelector, options = {}) { + deprecate( + 'find-element', + '`findElement(` is deprecated. Please, consider using the `findOne(` or `findMany(` instead.', + '2.2.0', + '3.0.0' + ); + const selector = buildSelector(pageObjectNode, targetSelector, options); const container = getContainer(pageObjectNode, options); diff --git a/docs/guides/deprecations.md b/docs/guides/deprecations.md new file mode 100644 index 00000000..861ee0ee --- /dev/null +++ b/docs/guides/deprecations.md @@ -0,0 +1,72 @@ +--- +layout: page +title: Deprecations +--- + +This is a list of deprecations introduced in 2.x cycle: + +## Find element + +**ID**: ember-cli-page-object.find-element + +**Until**: 3.0.0 + +Both `findElement(` and `findElementWithAssert()` have jQuery collection as their return value. Since we are going away from jQuery usage, these two finders are deprecated now. + +Please consider using `findOne(` or `findMany(` instead. + +Bad: + +```js +import { getter } from 'ember-cli-page-object/macros'; +import { findElementWithAssert } from 'ember-cli-page-object/extend'; + +export default function isDisabled(selector, options = {}) { + return getter(function() { + return findElementWithAssert(this, selector, options).is(':disabled'); + }); +} +``` + +Good: + +```js +import { getter } from 'ember-cli-page-object/macros'; +import { findOne } from 'ember-cli-page-object/extend'; + +export default function isDisabled(selector, options = {}) { + return getter(function() { + return findOne(this, selector, options).disabled; + }); +} + +``` + +Bad: + +```js +import { getter } from 'ember-cli-page-object/macros'; +import { findElement } from 'ember-cli-page-object/extend'; + +export default function count(selector, options = {}) { + return getter(function() { + return findElement(this, selector, { + ...options, + multiple: true + }).length; + }); +} +``` + +Good: + +```js +import { getter } from 'ember-cli-page-object/macros'; +import { findMany } from 'ember-cli-page-object/extend'; + +export default function count(selector, options = {}) { + return getter(function() { + return findMany(this, selector, options).length; + }); +} +``` diff --git a/docs/guides/extend.md b/docs/guides/extend.md index d2ba7b81..46a92199 100644 --- a/docs/guides/extend.md +++ b/docs/guides/extend.md @@ -71,14 +71,12 @@ export default function count(selector, options = {}) { } ``` -## findElementWithAssert +## findElementWithAssert (deprecated) [addon/-private/extend/find-element-with-assert.js:38-44](https://github.com/san650/ember-cli-page-object/blob/c521335ffba9955a6acaf1006ed503cbb61ba72d/addon/-private/extend/find-element-with-assert.js#L38-L44 "Source code on GitHub") Note: in the v2 series we are going to deprecate `findElementWithAssert`. It's recommended to migrate to use `findOne` instead. -In order to ease the migration, you may find useful the [`find-one`](https://github.com/ro0gr/ember-page-object-codemod/tree/master/transforms/find-one) codemod to perform the migration. - **Parameters** - `pageObjectNode` **Ceibo** Node of the tree @@ -106,12 +104,10 @@ export default function count(selector, options = {}) { } ``` -## findElement +## findElement (deprecated) [addon/-private/extend/find-element.js:36-42](https://github.com/san650/ember-cli-page-object/blob/c521335ffba9955a6acaf1006ed503cbb61ba72d/addon/-private/extend/find-element.js#L36-L42 "Source code on GitHub") -Note: in the v2 series we are going to deprecate `findElement`. It's recommended to migrate to use `findMany` instead. - **Parameters** - `pageObjectNode` **Ceibo** Node of the tree diff --git a/test-app/tests/integration/deprecations/find-element-test.ts b/test-app/tests/integration/deprecations/find-element-test.ts new file mode 100644 index 00000000..3f75f286 --- /dev/null +++ b/test-app/tests/integration/deprecations/find-element-test.ts @@ -0,0 +1,49 @@ +import { module, test } from 'qunit'; +import { create } from 'ember-cli-page-object'; +import deprecate from 'ember-cli-page-object/-private/deprecate'; +import hbs from 'htmlbars-inline-precompile'; +import { render } from '@ember/test-helpers'; +import { findElement, findElementWithAssert } from 'ember-cli-page-object/extend'; +import { setupRenderingTest } from '../../helpers'; + +module('Deprecation | find-element', function (hooks) { + setupRenderingTest(hooks); + + hooks.beforeEach(function () { + deprecate.__calls = []; + }); + + hooks.afterEach(function () { + delete deprecate.__calls; + }); + + test('findElement', async function (assert) { + await render(hbs``); + + findElement(create(), 'span'); + + assert.deepEqual(deprecate.__calls, [ + [ + "find-element", + "`findElement(` is deprecated. Please, consider using the `findOne(` or `findMany(` instead.", + "2.2.0", + "3.0.0" + ], + ]); + }); + + test('findElementWithAssert', async function (assert) { + await render(hbs``); + + findElementWithAssert(create(), 'span'); + + assert.deepEqual(deprecate.__calls, [ + [ + "find-element", + "`findElementWithAssert(` is deprecated. Please, consider using the `findOne(` instead.", + "2.2.0", + "3.0.0" + ], + ]); + }); +}); diff --git a/test-app/types/global.d.ts b/test-app/types/global.d.ts index 3a298cfe..67e11145 100644 --- a/test-app/types/global.d.ts +++ b/test-app/types/global.d.ts @@ -4,3 +4,29 @@ declare module 'ember-cli-page-object/templates/*' { const tmpl: TemplateFactory; export default tmpl; } + +declare module "ember-cli-page-object/-private/deprecate" { + const deprecate: { + (id: string, message: string, since: string, until: string): void; + + /** + Stores list of argments for each `deprecate(` invocation. + + It's `undefined` by default, which means "invocations tracking is disabled". + If you want to enable tracking, just initialize the `__calls` with an empty array, e.g: + + ```js + deprecate.__calls = []; + ``` + + or disable it with + + ```js + delete deprecate.__calls; + ``` + */ + __calls?: string[][] + }; + + export default deprecate +}