feat: add subscribeAndSpyOn (#8)

Co-authored-by: Shai Reznik <shairez@users.noreply.github.com>

Author: katharinakoal

README.md

@@ -8,7 +8,8 @@ A simple little class and a helper function that help make Observable testing a
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![codecov](https://img.shields.io/codecov/c/github/hirezio/observer-spy.svg)](https://codecov.io/gh/hirezio/observer-spy) <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END --> 
+
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 <div align="center">
   <a href="http://testangular.com/?utm_source=github&utm_medium=link&utm_campaign=observer-spy">
@@ -135,6 +136,32 @@ it('should spy on Observable errors', () => {
 });
 ```
 
+## Quick Usage with `subscribeAndSpyOn(observable)`
+
+You can also create an `ObserverSpy` and immediately subscribe to an observable with this simple helper function.
+Observer spies generated that way will provide an additional `unsubscribe()` method that you might want to call
+if your source observable does not complete or does not get terminated by an error while testing.
+
+**Example:**
+
+```js
+import { subscribeAndSpyOn } from '@hirez_io/observer-spy';
+
+it('should immediately subscribe and spy on Observable ', () => {
+  const fakeObservable = of('first', 'second', 'third');
+
+  // get an "ObserverSpyWithSubscription"
+  const observerSpy = subscribeAndSpyOn(fakeObservable);
+  // and optionally unsubscribe
+  observerSpy.unsubscribe();
+
+  expect(observerSpy.getFirstValue()).toEqual('first');
+
+  // or use the shorthand version:
+  expect(subscribeAndSpyOn(fakeObservable).getFirstValue()).toEqual('first');
+});
+```
+
 # Testing Async Observables
 
 #### `it('should do something', fakeTime((flush) => { ... flush(); });`
@@ -314,6 +341,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

src/index.ts

@@ -1,2 +1,3 @@
 export { ObserverSpy } from './observer-spy';
+export { subscribeAndSpyOn, ObserverSpyWithSubscription } from './subscribe-and-spy-on';
 export { fakeTime } from './fake-time';

src/subscribe-and-spy-on.spec.ts

@@ -0,0 +1,20 @@
+import { Subject } from 'rxjs';
+import { subscribeAndSpyOn } from './subscribe-and-spy-on';
+
+describe('subscribeAndSpyOn', () => {
+  it('should match with given subscription points', () => {
+    const fakeSubject = new Subject<number>();
+    fakeSubject.next(1);
+    const observerSpy = subscribeAndSpyOn(fakeSubject.asObservable());
+
+    fakeSubject.next(2);
+    fakeSubject.next(3);
+    observerSpy.unsubscribe();
+
+    fakeSubject.next(4);
+    fakeSubject.complete();
+
+    expect(observerSpy.getFirstValue()).toBe(2);
+    expect(observerSpy.getLastValue()).toBe(3);
+  });
+});

src/subscribe-and-spy-on.ts

@@ -0,0 +1,19 @@
+import { Observable, Subscription } from 'rxjs';
+import { ObserverSpy } from './observer-spy';
+
+export function subscribeAndSpyOn<T>(observableUnderTest: Observable<T>) {
+  return new ObserverSpyWithSubscription(observableUnderTest);
+}
+
+export class ObserverSpyWithSubscription<T> extends ObserverSpy<T> {
+  public subscription = new Subscription();
+
+  constructor(observableUnderTest: Observable<T>) {
+    super();
+    this.subscription.add(observableUnderTest.subscribe(this));
+  }
+
+  unsubscribe(): void {
+    this.subscription.unsubscribe();
+  }
+}