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
+}