docs(spec): show tests in ESDocs

Add ESDoc @test tag on each *-spec.js file in order to make it show in the ESDoc page, and also
tweak esdoc.json to show tests.

Author: staltz

.gitignore

@@ -13,6 +13,7 @@ dist/
 tmp/
 coverage/
 img/
+spec-js/
 
 # Misc
 npm-debug.log

.markdown-doctest-setup.js

@@ -1,7 +1,7 @@
 'use strict';
 var Rx = require(__dirname);
 
-var marbleTesting = require('./tmp/helpers/marble-testing');
+var marbleTesting = require('./spec-js/helpers/marble-testing');
 
 global.rxTestScheduler = new Rx.TestScheduler(marbleTesting.assertDeepEqual);
 

esdoc.json

@@ -1,6 +1,11 @@
 {
   "source": "./dist/es6",
   "destination": "./tmp/docs",
+  "test": {
+    "type": "mocha",
+    "source": "./spec-js",
+    "includes": ["(spec)\\.(js|ts)$"]
+  },
   "undocumentIdentifier": false,
   "title": "RxJS",
   "styles": ["./doc/styles/main.css"],

karma.conf.js

@@ -140,10 +140,10 @@ module.exports = function (config) {
     // list of files / patterns to load in the browser
     files: [
       'node_modules/babel-polyfill/dist/polyfill.js',
-      'tmp/helpers/marble-testing.js',
-      'tmp/helpers/test-helper.js',
-      'tmp/helpers/ajax-helper.js',
-      'tmp/**/*-spec.js'
+      'spec-js/helpers/marble-testing.js',
+      'spec-js/helpers/test-helper.js',
+      'spec-js/helpers/ajax-helper.js',
+      'spec-js/**/*-spec.js'
     ],
 
     // list of files to exclude
@@ -153,7 +153,7 @@ module.exports = function (config) {
     // preprocess matching files before serving them to the browser
     // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
     preprocessors: {
-      'tmp/**/*.js': ['browserify']
+      'spec-js/**/*.js': ['browserify']
     },
 
     // test results reporter to use

package.json

@@ -22,20 +22,20 @@
     "build_perf": "npm run build_cjs && npm run build_global && webdriver-manager update && npm run perf",
     "build_test": "rm -rf dist/ && npm run lint && npm run build_cjs && npm run test_buildonly && npm run test_nobuild",
     "build_cover": "rm -rf dist/ && npm run lint && npm run build_cjs && npm run test_buildonly && npm run cover",
-    "build_docs": "npm run build_es6 && npm run build_global && npm run tests2png && esdoc -c esdoc.json",
+    "build_docs": "npm run build_es6 && npm run build_global && npm run test_buildonly && npm run tests2png && esdoc -c esdoc.json",
     "publish_docs": "./publish_docs.sh",
     "lint_perf": "eslint perf/",
     "lint_spec": "tslint -c tslint.json spec/*.ts spec/**/*.ts spec/**/**/*.ts",
     "lint_src": "tslint -c tslint.json src/*.ts src/**/*.ts src/**/**/*.ts",
     "lint": "npm run lint_src && npm run lint_spec && npm run lint_perf",
     "copy_src": "cp -r src/ dist/cjs/src && cp -r src/ dist/amd/src && cp -r src/ dist/es6/src",
-    "cover": "istanbul cover -x \"*-spec.js index.js *-helper.js tmp/helpers/*\" ./node_modules/jasmine/bin/jasmine.js && npm run cover_remapping",
+    "cover": "istanbul cover -x \"*-spec.js index.js *-helper.js spec-js/helpers/*\" ./node_modules/jasmine/bin/jasmine.js && npm run cover_remapping",
     "cover_remapping": "remap-istanbul -b ./ -i coverage/coverage.json -o coverage/coverage-remapped.json && remap-istanbul -b ./ -i coverage/coverage.json -o coverage/coverage-remapped.lcov -t lcovonly && remap-istanbul -b ./ -i coverage/coverage.json -o coverage/coverage-remapped -t html",
     "test_nobuild": "jasmine",
-    "test_buildonly": "rm -rf tmp && tsc --project ./spec --pretty",
+    "test_buildonly": "rm -rf spec-js && mkdirp spec-js && tsc --project ./spec --pretty",
     "test": "npm run test_buildonly && npm run test_nobuild",
     "test_karma": "karma start karma.conf.js",
-    "tests2png": "mkdirp tmp/docs/img && cp -r spec/helpers/tests2png tmp/helpers/tests2png && jasmine JASMINE_CONFIG_PATH=spec/support/tests2png.json",
+    "tests2png": "npm run test_buildonly && mkdirp tmp/docs/img && mkdirp spec-js/support && cp spec/support/*.json spec-js/support/ && JASMINE_CONFIG_PATH=spec/support/tests2png.json jasmine",
     "watch": "watch \"echo triggering build && npm run build_test && echo build completed\" src -d -u -w=15",
     "perf": "protractor protractor.conf.js",
     "perf_micro": "node ./perf/micro/index.js",

spec/Notification-spec.ts

@@ -1,9 +1,9 @@
 import * as Rx from '../dist/cjs/Rx';
-import {expectObservable} from './helpers/marble-testing';
-import {it} from './helpers/test-helper';
+declare const expectObservable;
 
 const Notification = Rx.Notification;
 
+/** @test {Notification} */
 describe('Notification', () => {
   it('should exist', () => {
     expect(Notification).toBeDefined();

spec/Observable-spec.ts

@@ -1,5 +1,5 @@
 import * as Rx from '../dist/cjs/Rx';
-import {it, DoneSignature} from './helpers/test-helper';
+import {DoneSignature} from './helpers/test-helper';
 
 const Subscriber = Rx.Subscriber;
 const Observable = Rx.Observable;
@@ -14,6 +14,7 @@ function expectFullObserver(val) {
   expect(typeof val.isUnsubscribed).toBe('boolean');
 }
 
+/** @test {Observable} */
 describe('Observable', () => {
   it('should be constructed with a subscriber function', (done: DoneSignature) => {
     const source = new Observable(function (observer) {
@@ -280,6 +281,7 @@ describe('Observable', () => {
   });
 });
 
+/** @test {Observable} */
 describe('Observable.create', () => {
   it('should create an Observable', () => {
     const result = Observable.create(() => {
@@ -304,6 +306,7 @@ describe('Observable.create', () => {
   });
 });
 
+/** @test {Observable} */
 describe('Observable.lift', () => {
   it('should be overrideable in a custom Observable type that composes', (done: DoneSignature) => {
     class MyCustomObservable<T> extends Rx.Observable<T> {

spec/Scheduler-spec.ts

@@ -1,8 +1,9 @@
 import * as Rx from '../dist/cjs/Rx';
-import {it, DoneSignature} from './helpers/test-helper';
+import {DoneSignature} from './helpers/test-helper';
 
 const Scheduler = Rx.Scheduler;
 
+/** @test {Scheduler} */
 describe('Scheduler.queue', () => {
   it('should schedule things recursively', () => {
     let call1 = false;

spec/Subject-spec.ts

@@ -1,10 +1,11 @@
 import * as Rx from '../dist/cjs/Rx';
-import {hot, expectObservable} from './helpers/marble-testing';
-import {it, DoneSignature} from './helpers/test-helper';
+declare const {hot, expectObservable};
+import {DoneSignature} from './helpers/test-helper';
 
 const Subject = Rx.Subject;
 const Observable = Rx.Observable;
 
+/** @test {Subject} */
 describe('Subject', () => {
   it('should pump values right on through itself', (done: DoneSignature) => {
     const subject = new Subject();

spec/Subscriber-spec.ts

@@ -1,7 +1,7 @@
 import * as Rx from '../dist/cjs/Rx';
-import {it} from './helpers/test-helper';
 const Subscriber = Rx.Subscriber;
 
+/** @test {Subscriber} */
 describe('Subscriber', () => {
   it('should have the rxSubscriber symbol', () => {
     const sub = new Subscriber();

spec/Subscription-spec.ts

@@ -1,9 +1,10 @@
 import * as Rx from '../dist/cjs/Rx';
-import {it, DoneSignature} from './helpers/test-helper';
+import {DoneSignature} from './helpers/test-helper';
 
 const Observable = Rx.Observable;
 const Subscription = Rx.Subscription;
 
+/** @test {Subscription} */
 describe('Subscription', () => {
   it('should not leak', (done: DoneSignature) => {
     const tearDowns = [];

spec/helpers/test-helper.ts

@@ -11,9 +11,14 @@ jasmine.DEFAULT_TIMEOUT_INTERVAL = 5000;
 import * as _ from 'lodash';
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
 import {root} from '../../dist/cjs/util/root';
-import {assertDeepEqual} from './marble-testing';
+import * as marbleHelpers from './marble-testing';
 
 global.rxTestScheduler = null;
+global.cold = marbleHelpers.cold;
+global.hot = marbleHelpers.hot;
+global.time = marbleHelpers.time;
+global.expectObservable = marbleHelpers.expectObservable;
+global.expectSubscriptions = marbleHelpers.expectSubscriptions;
 
 //amending type definition of jasmine which seems doesn't have this
 export interface DoneSignature {
@@ -25,7 +30,7 @@ const defaultAssertion: (expectation: string, assertion?: (done: DoneSignature)
 const singleAssertion: (expectation: string, assertion?: (done: DoneSignature) => void, timeout?: number) => void = global.fit;
 
 function assertAction(done: DoneSignature, assertion: (done?: DoneSignature) => void): void {
-  global.rxTestScheduler = new Rx.TestScheduler(assertDeepEqual);
+  global.rxTestScheduler = new Rx.TestScheduler(marbleHelpers.assertDeepEqual);
   let error: any;
   let errorHappened: boolean = false;
 
@@ -45,9 +50,6 @@ function assertAction(done: DoneSignature, assertion: (done?: DoneSignature) =>
 }
 
 export function asDiagram(expectation: string): (expectation: string, assertion?: (done: DoneSignature) => void, timeout?: number) => void {
-  if (global.it.asDiagram) {
-    return global.it.asDiagram(expectation);
-  }
   return it;
 }
 
@@ -71,6 +73,12 @@ export function fit(expectation: string, assertion?: (done?: DoneSignature) => v
   }
 }
 
+global.it = it;
+global.fit = fit;
+if (!global.asDiagram) {
+  global.asDiagram = asDiagram;
+}
+
 export function lowerCaseO<T>(...args): Rx.Observable<T> {
   const values = [].slice.apply(arguments);
 

spec/helpers/tests2png/diagram-test-runner.js

@@ -76,7 +76,7 @@ var glit = global.it;
 
 global.it = function (description, specFn, timeout) { };
 
-global.it.asDiagram = function asDiagram(operatorLabel) {
+global.asDiagram = function asDiagram(operatorLabel) {
   return function specFnWithPainter(description, specFn) {
     if (specFn.length === 0) {
       glit(description, function () {
@@ -156,4 +156,3 @@ global.lowerCaseO = function lowerCaseO() {
 
   return o;
 };
-

spec/observables/ErrorObservable-spec.ts

@@ -1,10 +1,10 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
 import {ErrorObservable} from '../../dist/cjs/observable/ErrorObservable';
-import {expectObservable} from '../helpers/marble-testing';
-import {it} from '../helpers/test-helper';
+declare const expectObservable: any;
 
 declare const rxTestScheduler: Rx.TestScheduler;
 
+/** @test {throw} */
 describe('ErrorObservable', () => {
   it('should create expose a error property', () => {
     const e = new ErrorObservable('error');

spec/observables/IteratorObservable-spec.ts

@@ -1,7 +1,7 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
 import {IteratorObservable} from '../../dist/cjs/observable/IteratorObservable';
-import {expectObservable} from '../helpers/marble-testing';
-import {it, DoneSignature} from '../helpers/test-helper';
+declare const {expectObservable};
+import {DoneSignature} from '../helpers/test-helper';
 
 declare const rxTestScheduler: Rx.TestScheduler;
 

spec/observables/ScalarObservable-spec.ts

@@ -1,6 +1,5 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
 import {ScalarObservable} from '../../dist/cjs/observable/ScalarObservable';
-import {it} from '../helpers/test-helper';
 
 declare const rxTestScheduler: Rx.TestScheduler;
 

spec/observables/SubscribeOnObservable-spec.ts

@@ -1,7 +1,6 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
 import {SubscribeOnObservable} from '../../dist/cjs/observable/SubscribeOnObservable';
-import {hot, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
-import {it} from '../helpers/test-helper';
+declare const {hot, expectObservable, expectSubscriptions};
 
 declare const rxTestScheduler: Rx.TestScheduler;
 

spec/observables/bindCallback-spec.ts

@@ -1,9 +1,10 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
-import {it, DoneSignature} from '../helpers/test-helper';
+import {DoneSignature} from '../helpers/test-helper';
 
 declare const rxTestScheduler: Rx.TestScheduler;
 const Observable = Rx.Observable;
 
+/** @test {bindCallback} */
 describe('Observable.bindCallback', () => {
   describe('when not scheduled', () => {
     it('should emit one value from a callback', () => {

spec/observables/bindNodeCallback-spec.ts

@@ -1,9 +1,10 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
-import {it, DoneSignature} from '../helpers/test-helper';
+import {DoneSignature} from '../helpers/test-helper';
 
 declare const rxTestScheduler: Rx.TestScheduler;
 const Observable = Rx.Observable;
 
+/** @test {bindNodeCallback} */
 describe('Observable.bindNodeCallback', () => {
   describe('when not scheduled', () => {
     it('should emit one value from a callback', () => {

spec/observables/combineLatest-spec.ts

@@ -1,10 +1,11 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
-import {hot, cold, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
-import {it, DoneSignature} from '../helpers/test-helper';
+declare const {hot, cold, expectObservable, expectSubscriptions};
+import {DoneSignature} from '../helpers/test-helper';
 
 const Observable = Rx.Observable;
 const queueScheduler = Rx.Scheduler.queue;
 
+/** @test {combineLatest} */
 describe('Observable.combineLatest', () => {
   it('should combineLatest the provided observables', () => {
     const firstSource =  hot('----a----b----c----|');

spec/observables/concat-spec.ts

@@ -1,11 +1,12 @@
 /* globals describe, it, expect, expectObservable, expectSubscriptions, cold */
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
-import {hot, cold, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
-import {it, DoneSignature} from '../helpers/test-helper';
+declare const {hot, cold, expectObservable, expectSubscriptions};
+import {DoneSignature} from '../helpers/test-helper';
 
 const Observable = Rx.Observable;
 const queueScheduler = Rx.Scheduler.queue;
 
+/** @test {concat} */
 describe('Observable.concat', () => {
   it('should emit elements from multiple sources', () => {
     const e1 =  cold('-a-b-c-|');

spec/observables/defer-spec.ts

@@ -1,9 +1,9 @@
 import * as Rx from '../../dist/cjs/Rx';
-import {hot, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
-import {it} from '../helpers/test-helper';
+declare const {hot, expectObservable, expectSubscriptions};
 
 const Observable = Rx.Observable;
 
+/** @test {defer} */
 describe('Observable.defer', () => {
   it('should create an observable from the provided observbale factory', () => {
     const source = hot('--a--b--c--|');

spec/observables/dom/ajax-spec.ts

@@ -1,10 +1,10 @@
 import * as Rx from '../../../dist/cjs/Rx.DOM';
 import {root} from '../../../dist/cjs/util/root';
 import {MockXMLHttpRequest} from '../../helpers/ajax-helper';
-import {it} from '../../helpers/test-helper';
 
 declare const global: any;
 
+/** @test {ajax} */
 describe('Observable.ajax', () => {
   let gXHR: XMLHttpRequest;
   let rXHR: XMLHttpRequest;

spec/observables/dom/webSocket-spec.ts

@@ -1,6 +1,5 @@
 import * as Rx from '../../../dist/cjs/Rx.DOM';
 import {MockWebSocket} from '../../helpers/ajax-helper';
-import {it} from '../../helpers/test-helper';
 
 declare const __root__: any;
 
@@ -18,6 +17,7 @@ function teardownMockWebSocket() {
   MockWebSocket.clearSockets();
 }
 
+/** @test {webSocket} */
 describe('Observable.webSocket', () => {
   beforeEach(() => {
     setupMockWebSocket();

spec/observables/forkJoin-spec.ts

@@ -1,9 +1,10 @@
 import * as Rx from '../../dist/cjs/Rx.KitchenSink';
-import {hot, expectObservable} from '../helpers/marble-testing';
-import {it, DoneSignature, lowerCaseO} from '../helpers/test-helper';
+declare const {hot, expectObservable};
+import {DoneSignature, lowerCaseO} from '../helpers/test-helper';
 
 const Observable = Rx.Observable;
 
+/** @test {forkJoin} */
 describe('Observable.forkJoin', () => {
   it('should join the last values of the provided observables into an array', () => {
     const e1 = Observable.forkJoin(

spec/observables/from-promise-spec.ts

@@ -1,9 +1,10 @@
 import * as Rx from '../../dist/cjs/Rx';
-import {it, DoneSignature} from '../helpers/test-helper';
+import {DoneSignature} from '../helpers/test-helper';
 
 declare const process: any;
 const Observable = Rx.Observable;
 
+/** @test {fromPromise} */
 describe('Observable.fromPromise', () => {
   it('should emit one value from a resolved promise', (done: DoneSignature) => {
     const promise = Promise.resolve(42);