Use legacy collection in corner case

Also, link to migration guide in legacy collection warnings.

addon/-private/properties/collection.js

@@ -114,14 +114,40 @@ import { collection as legacyCollection } from './collection/legacy';
  * @return {Descriptor}
  */
 export function collection(definition) {
-  if ('itemScope' in definition) {
+  if (useLegacyAPI(definition)) {
     deprecate('You are currently using the legacy collection API, check the documentation to see how to upgrade to the new API.', false, {
       id: 'ember-cli-page-object.old-collection-api',
-      until: '2.0.0'
+      until: '2.0.0',
+      url: 'https://gist.github.com/san650/17174e4b7b1fd80b049a47eb456a7cdc#file-old-collection-api-js',
     });
 
     return legacyCollection(definition);
   } else {
     return mainCollection(definition);
   }
 }
+
+function useLegacyAPI(definition) {
+  // We test the use of `itemScope` attribute to guess that the users are using
+  // the legacy API.
+  //
+  // Also, there's a common mistake in page objects created in the wild that
+  // don't define the `itemScope` attribute but they do implement the `items`
+  // object.
+  //
+  //     var page = create({
+  //       foo: collection({
+  //         scope: '.foo',
+  //         item: {
+  //           text: text('p')
+  //         }
+  //       })
+  //     });
+  //
+  // Although this doesn't make any sense and doesn't work in legacy
+  // collections definitions, using the new collection API in this cases break
+  // tests suites. For that reason we use the legacy definition and print a
+  // deprecation warning.
+  return ('itemScope' in definition) ||
+    ('scope' in definition && 'item' in definition);
+}

tests/integration/deprecations/comma-separated-selector-test.js

@@ -7,7 +7,7 @@ import PageObject from 'dummy/tests/page-object';
 // only in the `moduleForComponent` test helper. Unfortunatelly it requires
 // some component name to be passed as a first argument. That's why we pass
 // a `calculating-device` here despite the fact that we don't actually need it.
-moduleForComponent('calculating-device', 'Integration | comma separated selectors', {
+moduleForComponent('calculating-device', 'Deprecation | comma separated selectors', {
   integration: true
 });
 

tests/integration/deprecations/legacy-collection-test.js

@@ -0,0 +1,45 @@
+import { moduleForComponent, test } from 'ember-qunit';
+
+import { create, collection } from 'ember-cli-page-object';
+
+moduleForComponent('calculating-device', 'Deprecation | legacy collection', {
+  integration: true
+});
+
+test('usage of itemScope in definition leads to the deprecation', function(assert) {
+  let page = create({
+    foo: collection({
+      itemScope: 'li'
+    })
+  });
+
+  page.foo();
+
+  assert.expectDeprecation('You are currently using the legacy collection API, check the documentation to see how to upgrade to the new API.');
+});
+
+test('usage of scope plus item leads to the deprecation', function(assert) {
+  let page = create({
+    foo: collection({
+      scope: 'foo',
+      item: {}
+    })
+  });
+
+  page.foo();
+
+  assert.expectDeprecation('You are currently using the legacy collection API, check the documentation to see how to upgrade to the new API.');
+});
+
+test('usage of scope without item does not lead to the deprecation', function(assert) {
+  let page = create({
+    foo: collection({
+      scope: 'foo',
+      bar: {}
+    })
+  });
+
+  page.foo;
+
+  assert.expectNoDeprecation();
+});