feat(faketime): added fakeTime wrapper function

fakeTime allows you to test async Observables using the VirtualTimeScheduler behind the scenes

Author: shairez

README.md

@@ -95,3 +95,106 @@ it('should spy on Observable errors', () => {
   expect(observerSpy.getError()).toEqual('FAKE ERROR');
 });
 ```
+
+# Testing Async Observables
+
+### ▶ For _Angular_ code - just use `fakeAsync`
+
+Example:
+
+```js
+it('should test Angular code with delay', fakeAsync(() => {
+  const observerSpy = new ObserverSpy();
+
+  const fakeObservable = of('fake value').pipe(delay(1000));
+
+  const sub = fakeObservable.subscribe(observerSpy);
+
+  tick(1000);
+
+  sub.unsubscribe();
+
+  expect(observerSpy.getLastValue()).toEqual('fake value');
+}));
+```
+
+### ▶ For only _promises_ (no timeouts / intervals) - just use `done`
+
+You don't even need to use an observer spy
+
+Example:
+
+```js
+it('should work with promises', (done) => {
+  const observerSpy: ObserverSpy<string> = new ObserverSpy();
+
+  const fakeService = {
+    getData() {
+      return Promise.resolve('fake data');
+    },
+  };
+  const fakeObservable = of('').pipe(switchMap(() => fakeService.getData()));
+
+  fakeObservable.subscribe(observerSpy);
+
+  observerSpy.onComplete(() => {
+    expect(observerSpy.getLastValue()).toEqual('fake data');
+    done();
+  });
+});
+```
+
+### ▶ For _time based_ rxjs code (timeouts / intervals / animations) - use `fakeTime`
+
+`fakeTime` is a utility function that wraps the test callback.
+
+It does the following things:
+
+1. Changes the `AsyncScheduler` delegate to use `VirtualTimeScheduler` (which gives you the ability to use "virtual time" instead of having long tests.
+2. Passes a `flush` function you can call to `flush()` when you want to virtually pass time forward.
+3. Works well with `done` if you pass it as the second parameter (instead of the first)
+
+Example:
+
+```js
+it(
+  'should handle delays with a virtual scheduler',
+  fakeTime((flush) => {
+    const VALUES = ['first', 'second', 'third'];
+    const observerSpy: ObserverSpy<string> = new ObserverSpy();
+    const delayedObservable: Observable<string> = of(...VALUES).pipe(delay(20000));
+
+    const sub = delayedObservable.subscribe(observerSpy);
+    flush();
+    sub.unsubscribe();
+
+    expect(observerSpy.getValues()).toEqual(VALUES);
+  })
+);
+
+it(
+  'should handle be able to deal with done functionality as well',
+  fakeTime((flush, done) => {
+    const VALUES = ['first', 'second', 'third'];
+    const observerSpy: ObserverSpy<string> = new ObserverSpy();
+    const delayedObservable: Observable<string> = of(...VALUES).pipe(delay(20000));
+
+    const sub = delayedObservable.subscribe(observerSpy);
+    flush();
+    sub.unsubscribe();
+
+    observerSpy.onComplete(() => {
+      expect(observerSpy.getValues()).toEqual(VALUES);
+      done();
+    });
+  })
+);
+```
+
+### ▶ For _ajax_ calls (http) - they shouldn't be tested in a unit / micro test... 😜
+
+Yeah. Test those in an integration test
+
+## Wanna learn more?
+
+In my [class testing In action course](http://testangular.com/?utm_source=github&utm_medium=link&utm_campaign=observer-spy) I go over all the differences and show you how to use this library to test stuff like `switchMap`, `interval` etc...

src/__snapshots__/fake-time.spec.ts.snap

@@ -0,0 +1,8 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`fakeTime should fail with no parameters 1`] = `
+"
+    \\"fakeTime()\\" callback must be declared with at least one parameter
+    For example: fakeAsync((flush)=> ...)
+    "
+`;

src/fake-time.spec.ts

@@ -0,0 +1,54 @@
+import { ObserverSpy } from './observer-spy';
+import { Observable, of } from 'rxjs';
+import { delay } from 'rxjs/operators';
+import { fakeTime } from './fake-time';
+
+describe('fakeTime', () => {
+  function getDelayedObservable() {
+    const VALUES = ['first', 'second', 'third'];
+    const observerSpy: ObserverSpy<string> = new ObserverSpy();
+    const delayedObservable: Observable<string> = of(...VALUES).pipe(delay(20000));
+
+    return {
+      VALUES,
+      observerSpy,
+      delayedObservable,
+    };
+  }
+
+  it('should fail with no parameters', () => {
+    function fakeTimeWithNoParams() {
+      fakeTime(() => {});
+    }
+    expect(fakeTimeWithNoParams).toThrowErrorMatchingSnapshot();
+  });
+
+  it(
+    'should handle delays with a virtual scheduler',
+    fakeTime((flush) => {
+      const { observerSpy, delayedObservable, VALUES } = getDelayedObservable();
+
+      const sub = delayedObservable.subscribe(observerSpy);
+      flush();
+      sub.unsubscribe();
+
+      expect(observerSpy.getValues()).toEqual(VALUES);
+    })
+  );
+
+  it(
+    'should handle be able to deal with done functionality as well',
+    fakeTime((flush, done) => {
+      const { observerSpy, delayedObservable, VALUES } = getDelayedObservable();
+
+      const sub = delayedObservable.subscribe(observerSpy);
+      flush();
+      sub.unsubscribe();
+
+      observerSpy.onComplete(() => {
+        expect(observerSpy.getValues()).toEqual(VALUES);
+        done();
+      });
+    })
+  );
+});

src/fake-time.ts

@@ -0,0 +1,41 @@
+import { VirtualTimeScheduler } from 'rxjs';
+import { AsyncScheduler } from 'rxjs/internal/scheduler/AsyncScheduler';
+
+export function fakeTime(callback: (...args: any[]) => any) {
+  if (callback.length === 0) {
+    throw new Error(`
+    "fakeTime()" callback must be declared with at least one parameter
+    For example: fakeAsync((flush)=> ...)
+    `);
+  }
+
+  if (callback.length === 1) {
+    return function () {
+      const virtualScheduler = new VirtualTimeScheduler();
+      AsyncScheduler.delegate = virtualScheduler;
+
+      function customFlush() {
+        virtualScheduler.flush();
+      }
+      const originalReturnedValue = callback(customFlush);
+
+      AsyncScheduler.delegate = undefined;
+
+      return originalReturnedValue;
+    };
+  }
+
+  return function (done: () => void) {
+    const virtualScheduler = new VirtualTimeScheduler();
+    AsyncScheduler.delegate = virtualScheduler;
+
+    function customFlush() {
+      virtualScheduler.flush();
+    }
+    const originalReturnedValue = callback(customFlush, done);
+
+    AsyncScheduler.delegate = undefined;
+
+    return originalReturnedValue;
+  };
+}