feat: 🎸 expose event creators (#355)

Author: twittwer

.all-contributorsrc

@@ -443,6 +443,16 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "twittwer",
+      "name": "Tobias Wittwer",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/8677948?v=4",
+      "profile": "https://github.com/twittwer",
+      "contributions": [
+        "code",
+        "doc"
+      ]
     }
   ]
 }

README.md

@@ -2,7 +2,7 @@
  <img width="100%" height="100%" src="https://raw.githubusercontent.com/ngneat/spectator/master/image.svg?sanitize=true">
 </p>
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-47-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-48-orange.svg?style=flat-square)](#contributors)
 [![spectator](https://img.shields.io/badge/tested%20with-spectator-2196F3.svg?style=flat-square)]()
 [![MIT](https://img.shields.io/packagist/l/doctrine/orm.svg?style=flat-square)]()
 [![commitizen](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)]()
@@ -36,6 +36,7 @@ Spectator helps you get rid of all the boilerplate grunt work, leaving you with
 - [Testing Components](#testing-components)
   - [Events API](#events-api)
     - [Custom Events](#custom-events)
+    - [Event Creators](#event-creators)
   - [Keyboard helpers](#keyboard-helpers)
   - [Mouse helpers](#mouse-helpers)
   - [Queries](#queries)
@@ -225,7 +226,7 @@ spectator.typeInElement(value, byText('Element'));
 spectator.dispatchMouseEvent(SpectatorElement, 'mouseout');
 spectator.dispatchMouseEvent(SpectatorElement, 'mouseout'), x, y, event);
 spectator.dispatchMouseEvent(byText('Element'), 'mouseout');
-spectator.dispatchMouseEvent(byText('Element'), 'mouseout'), x, y, event);
+spectator.dispatchMouseEvent(byText('Element'), 'mouseout', x, y, event);
 ```
 - `dispatchKeyboardEvent()` - Triggers a keyboard event:
 ```ts
@@ -248,6 +249,17 @@ spectator.triggerEventHandler(MyChildComponent, 'myCustomEvent', 'eventValue');
 spectator.triggerEventHandler('app-child-component', 'myCustomEvent', 'eventValue');
 ```
 
+#### Event Creators
+
+In case you want to test events independently of any template (e.g. in presenter services) you can fallback on the underlying event creators.
+They are basically providing the same signature without the preceding element.
+```ts
+const keyboardEvent = createKeyboardEvent('keyup', 'ArrowDown'/*, targetElement */);
+const mouseEvent = createMouseEvent('mouseout');
+const touchEvent = createTouchEvent('touchmove');
+const fakeEvent = createFakeEvent('input');
+```
+
 ### Keyboard helpers
 ```ts
 spectator.keyboard.pressEnter();
@@ -1153,7 +1165,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 | [<img src="https://avatars1.githubusercontent.com/u/20629635?v=4" width="100px;"/><br /><sub><b>Chris Cooper</b></sub>](https://github.com/cjcoops)<br />[💻](https://github.com/ngneat/spectator/commits?author=cjcoops "Code") | [<img src="https://avatars1.githubusercontent.com/u/5886709?v=4" width="100px;"/><br /><sub><b>Marc Scheib</b></sub>](https://github.com/MarcScheib)<br />[📖](https://github.com/ngneat/spectator/commits?author=MarcScheib "Documentation") | [<img src="https://avatars1.githubusercontent.com/u/2036391?v=4" width="100px;"/><br /><sub><b>dgsmith2</b></sub>](https://github.com/dgsmith2)<br />[💻](https://github.com/ngneat/spectator/commits?author=dgsmith2 "Code") | [<img src="https://avatars1.githubusercontent.com/u/50801476?v=4" width="100px;"/><br /><sub><b>dedwardstech</b></sub>](https://github.com/dedwardstech)<br />[💻](https://github.com/ngneat/spectator/commits?author=dedwardstech "Code") [🤔](#ideas-dedwardstech "Ideas, Planning, & Feedback") | [<img src="https://avatars2.githubusercontent.com/u/11571461?v=4" width="100px;"/><br /><sub><b>tamasfoldi</b></sub>](https://github.com/tamasfoldi)<br />[💻](https://github.com/ngneat/spectator/commits?author=tamasfoldi "Code") [🤔](#ideas-tamasfoldi "Ideas, Planning, & Feedback") | [<img src="https://avatars0.githubusercontent.com/u/10036108?v=4" width="100px;"/><br /><sub><b>Paolo Caleffi</b></sub>](https://github.com/IlCallo)<br />[💻](https://github.com/ngneat/spectator/commits?author=IlCallo "Code") | [<img src="https://avatars2.githubusercontent.com/u/7110786?v=4" width="100px;"/><br /><sub><b>Toni Villena</b></sub>](https://github.com/tonivj5)<br />[💻](https://github.com/ngneat/spectator/commits?author=tonivj5 "Code") |
 | [<img src="https://avatars2.githubusercontent.com/u/6719615?v=4" width="100px;"/><br /><sub><b>Itay Oded</b></sub>](https://github.com/itayod)<br />[💻](https://github.com/ngneat/spectator/commits?author=itayod "Code") | [<img src="https://avatars0.githubusercontent.com/u/1236069?v=4" width="100px;"/><br /><sub><b>Guillaume de Jabrun</b></sub>](https://twitter.com/Wykks)<br />[💻](https://github.com/ngneat/spectator/commits?author=Wykks "Code") | [<img src="https://avatars2.githubusercontent.com/u/5392144?v=4" width="100px;"/><br /><sub><b>Anand Tiwary</b></sub>](https://github.com/codeNoobie)<br />[💻](https://github.com/ngneat/spectator/commits?author=codeNoobie "Code") | [<img src="https://avatars3.githubusercontent.com/u/13190278?v=4" width="100px;"/><br /><sub><b>Ales Doganoc</b></sub>](https://github.com/AlesDo)<br />[💻](https://github.com/ngneat/spectator/commits?author=AlesDo "Code") | [<img src="https://avatars3.githubusercontent.com/u/1009783?v=4" width="100px;"/><br /><sub><b>Zoltan</b></sub>](https://zoltan.nz)<br />[💻](https://github.com/ngneat/spectator/commits?author=zoltan-nz "Code") | [<img src="https://avatars1.githubusercontent.com/u/13370430?v=4" width="100px;"/><br /><sub><b>Vitalii Baziuk</b></sub>](https://github.com/Coffee-Tea)<br />[💻](https://github.com/ngneat/spectator/commits?author=Coffee-Tea "Code") | [<img src="https://avatars0.githubusercontent.com/u/50454150?v=4" width="100px;"/><br /><sub><b>clementlemarc-certua</b></sub>](https://github.com/clementlemarc-certua)<br />[💻](https://github.com/ngneat/spectator/commits?author=clementlemarc-certua "Code") |
 | [<img src="https://avatars1.githubusercontent.com/u/302213?v=4" width="100px;"/><br /><sub><b>Yuriy Grunin</b></sub>](https://github.com/th0r)<br />[💻](https://github.com/ngneat/spectator/commits?author=th0r "Code") | [<img src="https://avatars2.githubusercontent.com/u/11780854?v=4" width="100px;"/><br /><sub><b>Andrey Chalkin</b></sub>](https://t.me/L2jLiga)<br />[💻](https://github.com/ngneat/spectator/commits?author=L2jLiga "Code") | [<img src="https://avatars3.githubusercontent.com/u/7720242?s=400&v=4" width="100px;"/><br /><sub><b>Steven Harris</b></sub>](https://stevenharrisdev.com)<br />[💻](https://github.com/ngneat/spectator/commits?author=Steven-Harris "Code") [📖](https://github.com/ngneat/spectator/commits?author=Steven-Harris "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/4697912?v=4" width="100px;"/><br /><sub><b>Richard Sahrakorpi</b></sub>](http://rjgunning.com)<br />[💻](https://github.com/ngneat/spectator/commits?author=RGunning "Code") | [<img src="https://avatars2.githubusercontent.com/u/13023533?v=4" width="100px;"/><br /><sub><b>Dominik Kremer</b></sub>](https://github.com/kremerd)<br />[💻](https://github.com/ngneat/spectator/commits?author=kremerd "Code") | [<img src="https://avatars1.githubusercontent.com/u/5039606?v=4" width="100px;"/><br /><sub><b>Mehmet Ozan Turhan</b></sub>](https://medium.com/@ozanturhan)<br />[💻](https://github.com/ngneat/spectator/commits?author=ozanturhan "Code") | [<img src="https://avatars2.githubusercontent.com/u/13765663?v=4" width="100px;"/><br /><sub><b>Vlad Lashko</b></sub>](https://github.com/thunderer199)<br />[💻](https://github.com/ngneat/spectator/commits?author=thunderer199 "Code") |
-| [<img src="https://avatars0.githubusercontent.com/u/20136906?v=4" width="100px;"/><br /><sub><b>William Tjondrosuharto</b></sub>](https://github.com/williamjuan027)<br />[💻](https://github.com/ngneat/spectator/commits?author=williamjuan027 "Code") | [<img src="https://avatars0.githubusercontent.com/u/1752170?v=4" width="100px;"/><br /><sub><b>Chaz Gatian</b></sub>](https://twitter.com/Cgatian)<br />[💻](https://github.com/ngneat/spectator/commits?author=cgatian "Code") | [<img src="https://avatars2.githubusercontent.com/u/27703381?v=4" width="100px;"/><br /><sub><b>Pavel Korobov</b></sub>](https://github.com/shirados90)<br />[💻](https://github.com/ngneat/spectator/commits?author=shirados90 "Code") | [<img src="https://avatars3.githubusercontent.com/u/25953659?v=4" width="100px;"/><br /><sub><b>Enno Lohmann</b></sub>](https://github.com/EnnoLohmann)<br />[💻](https://github.com/ngneat/spectator/commits?author=EnnoLohmann "Code") | [<img src="https://avatars2.githubusercontent.com/u/5169399?v=4" width="100px;"/><br /><sub><b>Pawel Boguslawski</b></sub>](https://github.com/bogusweb)<br />[💻](https://github.com/ngneat/spectator/commits?author=bogusweb "Code") |
+| [<img src="https://avatars0.githubusercontent.com/u/20136906?v=4" width="100px;"/><br /><sub><b>William Tjondrosuharto</b></sub>](https://github.com/williamjuan027)<br />[💻](https://github.com/ngneat/spectator/commits?author=williamjuan027 "Code") | [<img src="https://avatars0.githubusercontent.com/u/1752170?v=4" width="100px;"/><br /><sub><b>Chaz Gatian</b></sub>](https://twitter.com/Cgatian)<br />[💻](https://github.com/ngneat/spectator/commits?author=cgatian "Code") | [<img src="https://avatars2.githubusercontent.com/u/27703381?v=4" width="100px;"/><br /><sub><b>Pavel Korobov</b></sub>](https://github.com/shirados90)<br />[💻](https://github.com/ngneat/spectator/commits?author=shirados90 "Code") | [<img src="https://avatars3.githubusercontent.com/u/25953659?v=4" width="100px;"/><br /><sub><b>Enno Lohmann</b></sub>](https://github.com/EnnoLohmann)<br />[💻](https://github.com/ngneat/spectator/commits?author=EnnoLohmann "Code") | [<img src="https://avatars2.githubusercontent.com/u/5169399?v=4" width="100px;"/><br /><sub><b>Pawel Boguslawski</b></sub>](https://github.com/bogusweb)<br />[💻](https://github.com/ngneat/spectator/commits?author=bogusweb "Code") | [<img src="https://avatars1.githubusercontent.com/u/8677948?v=4" width="100px;"/><br /><sub><b>Tobias Wittwer</b></sub>](https://github.com/twittwer)<br />[💻](https://github.com/ngneat/spectator/commits?author=twittwer "Code") [📖](https://github.com/ngneat/spectator/commits?author=twittwer "Documentation") |
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://allcontributors.org/docs/en/emoji-key) specification. Contributions of any kind welcome!

docs/docs/events.md

@@ -32,7 +32,7 @@ spectator.typeInElement(value, SpectatorElement);
 - `dispatchMouseEvent()` - Triggers a mouse event:
 ```ts
 spectator.dispatchMouseEvent(SpectatorElement, 'mouseout');
-spectator.dispatchMouseEvent(SpectatorElement, 'mouseout'), x, y, event);
+spectator.dispatchMouseEvent(SpectatorElement, 'mouseout', x, y, event);
 ```
 - `dispatchKeyboardEvent()` - Triggers a keyboard event:
 ```ts
@@ -51,3 +51,14 @@ You can trigger custom events (`@Output()` of child components) [using](https://
 spectator.triggerEventHandler(MyChildComponent, 'myCustomEvent', 'eventValue');
 spectator.triggerEventHandler('app-child-component', 'myCustomEvent', 'eventValue');
 ```
+
+## Event Creators
+
+In case you want to test events independently of any template (e.g. in presenter services) you can fallback on the underlying event creators.
+They are basically providing the same signature without the preceding element.
+```ts
+const keyboardEvent = createKeyboardEvent('keyup', 'ArrowDown'/*, targetElement */);
+const mouseEvent = createMouseEvent('mouseout');
+const touchEvent = createTouchEvent('touchmove');
+const fakeEvent = createFakeEvent('input');
+```

projects/spectator/src/lib/base/dom-spectator.ts

@@ -9,7 +9,7 @@ import { isString, QueryOptions, QueryType, SpectatorElement, EventEmitterType,
 import { SpyObject } from '../mock';
 import { getChildren, setProps } from '../internals/query';
 import { patchElementFocus } from '../internals/element-focus';
-import { createMouseEvent } from '../internals/event-objects';
+import { createMouseEvent } from '../event-creators';
 import { dispatchFakeEvent, dispatchKeyboardEvent, dispatchMouseEvent, dispatchTouchEvent } from '../dispatch-events';
 import { typeInElement } from '../type-in-element';
 import { selectOption } from '../select-option';

projects/spectator/src/lib/dispatch-events.ts

@@ -2,7 +2,7 @@
  * Credit - Angular Material
  */
 
-import { createFakeEvent, createKeyboardEvent, createMouseEvent, createTouchEvent } from './internals/event-objects';
+import { createFakeEvent, createKeyboardEvent, createMouseEvent, createTouchEvent } from './event-creators';
 import { KeyboardEventOptions } from './types';
 
 /**

projects/spectator/src/lib/internals/event-objects.ts renamed to projects/spectator/src/lib/event-creators.ts

@@ -2,8 +2,8 @@
  * Credit - Angular Material
  */
 
-import { parseKeyOptions } from './key-parser';
-import { KeyboardEventOptions } from '../types';
+import { parseKeyOptions } from './internals/key-parser';
+import { KeyboardEventOptions } from './types';
 
 /** Creates a browser MouseEvent with the specified options. */
 export function createMouseEvent(type: string, x: number = 0, y: number = 0, button: number = 0): MouseEvent {

projects/spectator/src/public_api.ts

@@ -41,4 +41,5 @@ export * from './lib/types';
 export { typeInElement } from './lib/type-in-element';
 export { defineGlobalsInjections } from './lib/globals-injections';
 export { dispatchEvent, dispatchFakeEvent, dispatchKeyboardEvent, dispatchMouseEvent, dispatchTouchEvent } from './lib/dispatch-events';
+export { createFakeEvent, createKeyboardEvent, createMouseEvent, createTouchEvent } from './lib/event-creators';
 export { MockComponentDeprecated, MockDirectiveDeprecated } from './lib/deprecated';