Re: [CommonJS] doctest

[Kevin Dangoor]

On Fri, Oct 9, 2009 at 10:20 AM, Daniel Friesen <nadir.s...@gmail.com> wrote:

I have a 3rd one.

3. Use doctest to write our tests.
It's easy to use. Doesn't need any discussion over what api to use cause there is no API. Implementation is actually quite a simple addition to a shell. Rhino already has it builtin so all Rhino implementations already have access to it. I already am using it in MonkeyScript for some Binary/C tests.

I'm not a fan, personally. My view is that doctests end up with yucky compromises in both the tests and the documentation. My alternative has been to write tests and sample code conveniently in normal source files that can do all of the good things you get from the language/library and then write docs that are pleasant to read and that pull in appropriate bits of code.

Kevin

--
Kevin Dangoor

work: http://labs.mozilla.com/
email: k...@blazingthings.com
blog: http://www.BlueSkyOnMars.com

[Daniel Friesen]

There's no requirement that doctest be used inside of documentation.

All doctest really is, is something that takes what looks like a shell
session, runs the code in it, and checks that the responses match up. If
they don't match up, then they output what went wrong with the output of
the code.
Whether you store them in documentation comments, or in test files just
like you would unit tests is irrelevant.

I wasn't even thinking of using them that way. I store doctests in my
tests/ folder and execute them.

~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]

Kevin Dangoor wrote:
> On Fri, Oct 9, 2009 at 10:20 AM, Daniel Friesen
> <nadir.s...@gmail.com <mailto:nadir.s...@gmail.com>> wrote:
>
> I have a 3rd one.
>
> 3. Use doctest

> <https://developer.mozilla.org/en/New_in_Rhino_1.7R2#Doctest> to

> write our tests.
> It's easy to use. Doesn't need any discussion over what api to use
> cause there is no API. Implementation is actually quite a simple
> addition to a shell. Rhino already has it builtin so all Rhino
> implementations already have access to it. I already am using it
> in MonkeyScript for some Binary/C tests.
>
>
> I'm not a fan, personally. My view is that doctests end up with yucky
> compromises in both the tests and the documentation. My alternative
> has been to write tests and sample code conveniently in normal source
> files that can do all of the good things you get from the
> language/library and then write docs that are pleasant to read and
> that pull in appropriate bits of code.
>
> Kevin
>
> --
> Kevin Dangoor
>
> work: http://labs.mozilla.com/

> email: k...@blazingthings.com <mailto:k...@blazingthings.com>
> blog: http://www.BlueSkyOnMars.com
>
> >

[Kevin Dangoor]

On Fri, Oct 9, 2009 at 11:18 AM, Daniel Friesen <nadir.s...@gmail.com> wrote:

There's no requirement that doctest be used inside of documentation.

All doctest really is, is something that takes what looks like a shell
session, runs the code in it, and checks that the responses match up. If
they don't match up, then they output what went wrong with the output of
the code.
Whether you store them in documentation comments, or in test files just
like you would unit tests is irrelevant.

I wasn't even thinking of using them that way. I store doctests in my
tests/ folder and execute them.

Ahh, I see. Yeah, that approach is a lot better than trying to mix docs and tests the way I've seen doctest generally used.

Kevin

--
Kevin Dangoor

work: http://labs.mozilla.com/
email: k...@blazingthings.com

blog: http://www.BlueSkyOnMars.com

[Daniel Friesen]

Yup, just for a taste example, here's what I have so far for my Blob tests.

js> var b = Blob([255]);
js> b.contentConstructor === Blob;
true
js> b.length;
1
js> b.byteCodeAt(0);
255
js> b.codeAt(0);
255
js> b.concat([255,234]).toSource();
(new Blob([255, 255, 234]))
js> // slice needs a test
js> Blob([1,2,3,4,5,6,7]).indexOf([3,4,5]);
2
js> b.byteAt(0).toSource();
(new Blob([255]))
js> b.valueAt(0).toSource();
(new Blob([255]))
js> Blob([0,0,0,255,0,0]).split([0,255]).toSource();
[(new Blob([0,0])),(new Blob([0,0]))]
js> // toBlob needs a test
js> // toString(fromCharset) needs a test
js> // toArray() needs a test
js> // toArray(fromCharset) needs a test
js> "".contentConstructor === String
true
js> // toBlob(toCharset) needs a test
js> // valueAt(index) needs a test
js> // codeAt(index) needs a test
js> // String.fromCode(code) needs a test

Course, I could make my toSource tests more portable by doing match
tests instead of using output.

~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]

Kevin Dangoor wrote:

[Kevin Dangoor]

On Fri, Oct 9, 2009 at 11:50 AM, Daniel Friesen <nadir.s...@gmail.com> wrote:

Yup, just for a taste example, here's what I have so far for my Blob tests.

js> var b = Blob([255]);
js> b.contentConstructor === Blob;
true

For what it's worth, I still prefer

var b = Blob([255]);

assert.equals(Blob, b.contentConstructor)
 
But I know that's entirely personal preference :)

Kevin

--
Kevin Dangoor

work: http://labs.mozilla.com/
email: k...@blazingthings.com

blog: http://www.BlueSkyOnMars.com

[Daniel Friesen]

----
js> var assert = require('assert');

js> var b = Blob([255]);

js> assert.equals(Blob, b.contentConstructor);
true
----
;) *snicker*

~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]

Kevin Dangoor wrote: