deprecate findElement and findElementWithAssert

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);
 

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;
+  });
+}
+```

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

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`<span></span>`);
+
+    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`<span></span>`);
+
+    findElementWithAssert(create(), 'span');
+
+    assert.deepEqual(deprecate.__calls, [
+      [
+        "find-element",
+        "`findElementWithAssert(` is deprecated. Please, consider using the `findOne(` instead.",
+        "2.2.0",
+        "3.0.0"
+      ],
+    ]);
+  });
+});

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