Standardize params for calling triggerEvent on file input

API.md

@@ -235,15 +235,14 @@ Triggers an event on the specified target.
 **Examples**
 
 Using triggerEvent to Upload a file
-When using triggerEvent to upload a file the `eventType` must be `change` and  you must pass an
-array of [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) as `options`.
+When using triggerEvent to upload a file the `eventType` must be `change` and you must pass the `options` param as an object with a key `files` containing an array of [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
 
 
 ```javascript
 triggerEvent(
   'input.fileUpload',
   'change',
-  [new Blob(['Ember Rules!'])]
+  { files: [new Blob(['Ember Rules!'])] }
 );
 ```
 

addon-test-support/@ember/test-helpers/dom/fire-event.js

@@ -1,4 +1,5 @@
 import { assign } from '@ember/polyfills';
+import { deprecate } from '@ember/application/deprecations';
 
 // eslint-disable-next-line require-jsdoc
 const MOUSE_EVENT_CONSTRUCTOR = (() => {
@@ -194,8 +195,23 @@ function buildKeyboardEvent(type, options = {}) {
 }
 
 // eslint-disable-next-line require-jsdoc
-function buildFileEvent(type, element, files = []) {
+function buildFileEvent(type, element, options = {}) {
   let event = buildBasicEvent(type);
+  let files;
+  if (Array.isArray(options)) {
+    deprecate(
+      'Passing the `options` param as an array to `triggerEvent` for file inputs is deprecated. Please pass an object with a key `files` containing the array instead.',
+      false,
+      {
+        id: 'ember-test-helpers.trigger-event.options-blob-array',
+        until: '0.8.0',
+      }
+    );
+
+    files = options;
+  } else {
+    files = options.files;
+  }
 
   if (files.length > 0) {
     Object.defineProperty(files, 'item', {

addon-test-support/@ember/test-helpers/dom/trigger-event.js

@@ -14,8 +14,9 @@ import { nextTickPromise } from '../-utils';
  *
  * @example
  * <caption>Using triggerEvent to Upload a file
- * When using triggerEvent to upload a file the `eventType` must be `change` and  you must pass an
- * array of [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) as `options`.</caption>
+ * When using triggerEvent to upload a file the `eventType` must be `change` and you must pass the
+ * `options` param as an object with a key `files` containing an array of
+ * [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob).</caption>
  *
  * triggerEvent(
  *   'input.fileUpload',

tests/unit/dom/select-files-test.js

@@ -50,4 +50,35 @@ module('DOM Helper: selectFiles', function(hooks) {
 
     assert.verifySteps(['change', 'text-file.txt', 'change', 'image-file.png']);
   });
+
+  test('it can trigger a file selection event with files passed in options as an object', async function(assert) {
+    element = buildInstrumentedElement('input');
+    element.setAttribute('type', 'file');
+
+    element.addEventListener('change', e => {
+      assert.step(e.target.files[0].name);
+    });
+
+    await setupContext(context);
+    await triggerEvent(element, 'change', { files: [textFile] });
+
+    assert.verifySteps(['change', 'text-file.txt']);
+  });
+
+  test('it can trigger a file selection event with files passed in options as an array but raises a deprecation warning', async function(assert) {
+    element = buildInstrumentedElement('input');
+    element.setAttribute('type', 'file');
+
+    element.addEventListener('change', e => {
+      assert.step(e.target.files[0].name);
+    });
+
+    await setupContext(context);
+    await triggerEvent(element, 'change', [textFile]);
+
+    assert.verifySteps(['change', 'text-file.txt']);
+    assert.deprecationsInclude(
+      'Passing the `options` param as an array to `triggerEvent` for file inputs is deprecated. Please pass an object with a key `files` containing the array instead.'
+    );
+  });
 });