docs(spec): show tests in ESDocs #1378

staltz · 2016-02-23T09:21:05Z

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.

To see this page live, open http://rxjs5-esdoc-tests.surge.sh/test.html

staltz · 2016-02-23T09:23:32Z

spec/operators/bufferCount-spec.js

@@ -2,6 +2,7 @@
 var Rx = require('../../dist/cjs/Rx');
 var Observable = Rx.Observable;

+/** @test {bufferCount} */


Usually these changes just add the tag, but in other cases...

kwonoj · 2016-02-23T17:37:00Z

(If) #1364 is landed, does it means this PR need to be updated as well?

staltz · 2016-02-23T18:26:13Z

I don't know... it depends whether git is smart to identify that just the filename extension changed, and can merge the new changes.

kwonoj · 2016-02-23T18:27:32Z

Seems we may know after changes are landed :) let's see how it'll goes, since #1364 is not certain to be accepted at this moment.

benlesh · 2016-03-01T00:59:41Z

This looks great.

kwonoj · 2016-03-01T17:55:47Z

@staltz , #1364 's checked in and seems it requires rebase. I'll check it this once it's done.

staltz · 2016-03-01T18:33:25Z

I'll rebase this tomorrow

staltz · 2016-03-02T11:23:07Z

Ok, just FYI, this is taking me some stress to rebase. ESDoc explicitly doesn't support TypeScript, so I need to compile all .ts tests to .js files, and the TS compilation isn't passing. It'll take some time to manually work this out.

staltz · 2016-03-02T13:47:17Z

@kwonoj we need to coordinate together the rebase I'm doing. I had to do some big changes:

change spec/helpers/test-helper.ts to patch global.it = it
not import it like import {it, asDiagram} from '../helpers/test-helper' in individual -spec.ts files because that would make TS compile to test_helper_1.it('should ... in -spec.js files, and that's bad for ESDoc which expects -spec.js files look like normal Mocha-style tests (with it calls inside describe calls)
Change the spec compilation output from tmp to spec-js because tmp also contains tmp/docs which in turn also has javascript files (ESDoc generates some javascript) and we don't want ESDoc looking at everything inside tmp. Also, we don't want the ESDoc page to show the official path for test files being tmp/something.

Can you provide some insight why did you change 1. and 2. from how it was before? Is it solving some problem?

staltz · 2016-03-02T15:18:41Z

Another thing I may change is

-import {hot, cold, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
 import {DoneSignature, asDiagram, lowerCaseO} from '../helpers/test-helper';
+declare const hot: any;
+declare const cold: any;
+declare const expectObservable: any;
+declare const expectSubscriptions: any;

in -spec.ts files and then

+import {assertDeepEqual, hot, cold, expectObservable, expectSubscriptions} from './marble-testing';

+global.cold = cold;
+global.hot = hot;
+global.expectObservable = expectObservable;
+global.expectSubscriptions = expectSubscriptions;

in spec/helpers/test-helper.ts

The result is that it makes the test file in ESDoc more readable:

Otherwise it looks like this:

Which is bad since we want tests (specially marble diagrams) to be additional documentation, it should be readable.

With TS2JS compilation, we lose those important whitespaces to align the ASCII marble diagrams though. I might need to try again doing a PR to TypeScript so we could add /* */ comments there to horizontally align those ASCII marble diagrams, like this:

But that has to be in a different PR, of course.

kwonoj · 2016-03-02T17:55:48Z

why did you change 1. and 2. from how it was before? Is it solving some problem?

: It was ergonomics changes to test cases to import helpers explicitly, intention to move forward test help to be modular without patching global variables any more. (though current still does have some) also provides type inferences to helper method too. Global patch would work, loses some conveniences though. Thinking about further plans, I'd like to have explicit export instead of global patching, but do not have great idea to solve this issue with preserving current way.

staltz · 2016-03-02T18:40:04Z

intention to move forward test help to be modular without patching global variables any more.

modular so that RxJS users can use the helpers too? And which helpers? I assume mainly hot, cold, etc, right? They are currently modular, packaged as helpers/marble-testing.ts. It's helpers/test-helper.ts which is doing the global patch.

I think with the current setup that we have (ESDoc only supporting JS/ES, no TS support), we have to do global patch. If we don't global patch e.g. it(), then we won't see test cases in the ESDoc test page.

When it comes to type testing our spec folder, I think the priority should to type test operators and Observables and actual RxJS stuff.

kwonoj · 2016-03-02T19:01:55Z

I assume mainly hot, cold, etc,

: and also was thought about test-helper to, which setup custom assertions to use hot / cold.

I think with the current setup that we have (ESDoc only supporting JS/ES, no TS support), we have to do global patch.

: Yes, I don't object that. Above comment was if I could achieve both, I'd like to have explicit export without global patching but for now global patching seems way to go for now.

staltz · 2016-03-02T20:08:18Z

Yeah, ESDoc not supporting TS is actually quite annoying. I've been able to get around it most of the time. Perhaps we could have looked into some other library that does straight conversion from TS -> docs, but there's probably even less tools that do that type of stuff.

Overall, I'm ok with hacking around ESDoc as we can. It's mostly useful.

kwonoj · 2016-03-02T22:33:38Z

Perhaps we could have looked into some other library that does straight conversion from TS -> docs

: Off-topic, but makes me curious - have we considered TypeDoc? (http://typedoc.io/) i.e unsupported feature we'd like to have, etcs?

staltz · 2016-03-03T08:08:02Z

Maybe we could use it, but it's unclear is it beneficial to move at this point. It doesn't seem to support showing the tests, and unclear does it support additional markdown pages organized in an outline.

kwonoj · 2016-03-03T08:12:36Z

it's unclear is it beneficial to move at this point.

: agreed, question's only for curiousity and not suggesting to migrate into. It could be cobsiderable only if pain of using esdoc is unbearable along with all features we'd like to have is being supported in typedoc.

staltz · 2016-03-03T12:22:12Z

Rebased. Also notice that I removed import {asDiagram} from 'test-helpers' because we have two different jasmine configurations, asDiagram is different for each, and we need to patch globally.

kwonoj · 2016-03-03T18:18:26Z

Sorry, may need another rebase :( I'll check in this once it's rebased.

@test

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.

staltz · 2016-03-04T08:33:24Z

Rebased ✅ :)

kwonoj · 2016-03-04T08:39:11Z

package.json

    "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",


just note : specifying JASMINE_CONFIG_PATH prior to command jasmine makes this script windows-incompatible (was reason I changed its order to let jasmine accept it as command argument)

no blocking issue though, I'll amend this later.

interesting to know, sorry for breaking it

this script is rarely being used, totally ok and I can amend it later quickly. :)

kwonoj · 2016-03-04T08:47:03Z

Merged with bd45a90, thanks @staltz

lock · 2018-06-07T08:03:18Z

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

staltz reviewed Feb 23, 2016
View reviewed changes

staltz force-pushed the esdoc-tests branch from 4c378b8 to 889541f Compare February 23, 2016 09:33

staltz mentioned this pull request Feb 23, 2016

Unclear Docs #1379

Closed

staltz force-pushed the esdoc-tests branch from 889541f to d891bf7 Compare February 29, 2016 08:41

benlesh added the PR: lgtm label Mar 1, 2016

staltz force-pushed the esdoc-tests branch 2 times, most recently from 5390b71 to 6bc98ef Compare March 3, 2016 12:21

docs(spec): show tests in ESDocs

bd45a90

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.

staltz force-pushed the esdoc-tests branch from 6bc98ef to bd45a90 Compare March 4, 2016 08:33

kwonoj reviewed Mar 4, 2016
View reviewed changes

kwonoj merged commit bd45a90 into ReactiveX:master Mar 4, 2016

staltz deleted the esdoc-tests branch March 4, 2016 08:49

MartinMuzatko mentioned this pull request Mar 8, 2016

docs(README): Add Information where Docs can be found #1441

Closed

kwonoj mentioned this pull request Apr 18, 2016

Losing type inferences in marble tests #1633

Closed

lock bot locked as resolved and limited conversation to collaborators Jun 7, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(spec): show tests in ESDocs #1378

docs(spec): show tests in ESDocs #1378

staltz commented Feb 23, 2016

staltz Feb 23, 2016

kwonoj commented Feb 23, 2016

staltz commented Feb 23, 2016

kwonoj commented Feb 23, 2016

benlesh commented Mar 1, 2016

kwonoj commented Mar 1, 2016

staltz commented Mar 1, 2016

staltz commented Mar 2, 2016

staltz commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 3, 2016

kwonoj commented Mar 3, 2016

staltz commented Mar 3, 2016

kwonoj commented Mar 3, 2016

staltz commented Mar 4, 2016

kwonoj Mar 4, 2016

staltz Mar 4, 2016

kwonoj Mar 4, 2016

kwonoj commented Mar 4, 2016

lock bot commented Jun 7, 2018

docs(spec): show tests in ESDocs #1378

docs(spec): show tests in ESDocs #1378

Conversation

staltz commented Feb 23, 2016

staltz Feb 23, 2016

Choose a reason for hiding this comment

kwonoj commented Feb 23, 2016

staltz commented Feb 23, 2016

kwonoj commented Feb 23, 2016

benlesh commented Mar 1, 2016

kwonoj commented Mar 1, 2016

staltz commented Mar 1, 2016

staltz commented Mar 2, 2016

staltz commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 2, 2016

kwonoj commented Mar 2, 2016

staltz commented Mar 3, 2016

kwonoj commented Mar 3, 2016

staltz commented Mar 3, 2016

kwonoj commented Mar 3, 2016

staltz commented Mar 4, 2016

kwonoj Mar 4, 2016

Choose a reason for hiding this comment

staltz Mar 4, 2016

Choose a reason for hiding this comment

kwonoj Mar 4, 2016

Choose a reason for hiding this comment

kwonoj commented Mar 4, 2016

lock bot commented Jun 7, 2018