From 829f4fb4cc66bd468e0611b07b8b3a1c6af7feb9 Mon Sep 17 00:00:00 2001
From: Jonathan Johnson <jon.johnson@ucsf.edu>
Date: Sun, 11 Mar 2018 21:04:13 -0700
Subject: [PATCH] Add some specific documentation for uploading files

Uploading files with an event is a specific code path and the task can
be tough to figure out without an example.
---
 API.md                                        | 14 ++++++++++
 .../@ember/test-helpers/dom/trigger-event.js  | 27 +++++++++++++------
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/API.md b/API.md
index 13b005e9f..6516308f3 100644
--- a/API.md
+++ b/API.md
@@ -170,6 +170,20 @@ Triggers an event on the specified target.
 -   `eventType` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the type of event to trigger
 -   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** additional properties to be set on the event
 
+**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`._
+
+```javascript
+triggerEvent(
+  'input.fileUpload',
+  'change',
+  [new Blob(['Ember Rules!'])]
+);
+```
+
 Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;void>** resolves when the application is settled
 
 ### triggerKeyEvent
diff --git a/addon-test-support/@ember/test-helpers/dom/trigger-event.js b/addon-test-support/@ember/test-helpers/dom/trigger-event.js
index a3c7485d0..d7394336f 100644
--- a/addon-test-support/@ember/test-helpers/dom/trigger-event.js
+++ b/addon-test-support/@ember/test-helpers/dom/trigger-event.js
@@ -4,14 +4,25 @@ import settled from '../settled';
 import { nextTickPromise } from '../-utils';
 
 /**
-  Triggers an event on the specified target.
-
-  @public
-  @param {string|Element} target the element or selector to trigger the event on
-  @param {string} eventType the type of event to trigger
-  @param {Object} options additional properties to be set on the event
-  @return {Promise<void>} resolves when the application is settled
-*/
+ * Triggers an event on the specified target.
+ *
+ * @public
+ * @param {string|Element} target the element or selector to trigger the event on
+ * @param {string} eventType the type of event to trigger
+ * @param {Object} options additional properties to be set on the event
+ * @return {Promise<void>} resolves when the application is settled
+ *
+ * @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>
+ *
+ * triggerEvent(
+ *   'input.fileUpload',
+ *   'change',
+ *   [new Blob(['Ember Rules!'])]
+ * );
+ */
 export default function triggerEvent(target, eventType, options) {
   return nextTickPromise().then(() => {
     if (!target) {