Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for a title, docstrings-tags and expose private methods #10

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
*doctest*
node_modules/
dist/
142 changes: 24 additions & 118 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,124 +1,30 @@
# doctest-ts: doctests for TypeScript

Say you have a file src/hasFoo.ts with a function like hasFoo:

```typescript
function hasFoo(s: string): boolean {
return null != s.match(/foo/i)
}
```

You can now make documentation and unit tests for this function in one go:

```typescript
/** Does this string contain foo, ignoring case?

hasFoo('___foo__') // => true
hasFoo(' fOO ') // => true
hasFoo('Foo.') // => true
hasFoo('bar') // => false
hasFoo('fo') // => false
hasFoo('oo') // => false

*/
function hasFoo(s: string): boolean {
return null != s.match(/foo/i)
# doctest-ts-improved: doctests for TypeScript

Easy doctests for typescript modules, including private methods and extra imports:

```
export default class SomeClass {
/**
* Gets the field doubled
* @example xyz
*
* import OtherClass from "./OtherClass";
*
* // Should equal 42
* SomeClass.get() // => 42
*
* SomeClass.get() + 1 // => 43
*
* new OtherClass().doSomething(new SomeClass()) // => 5
*/
private static get() : number{
// a comment
// @ts-ignore
return 42
}
}
```

Since the function is not exported we can only test this by either editing or copying the entire file and gluing on tests at the end.
This library goes for the second approach: making a copy of the file with the translated tests at the end. Run it like so:

```sh
$ doctest-ts src/hasFoo.ts
Writing src/hasFoo.doctest.ts
```

The contents of `src/hasFoo.doctest.ts` is the original file prepended to the doctests rewritten as unit tests.

```typescript
/** Does this string contain foo, ignoring case?

hasFoo('___foo__') // => true
hasFoo(' fOO ') // => true
hasFoo('Foo.') // => true
hasFoo('bar') // => false
hasFoo('fo') // => false
hasFoo('oo') // => false

*/
function hasFoo(s: string): boolean {
return null != s.match(/foo/i)
}

import * as __test from "tape"
__test("hasFoo", t => {t.deepEqual(hasFoo("___foo__"), true, "true")
t.deepEqual(hasFoo(" fOO "), true, "true")
t.deepEqual(hasFoo("Foo."), true, "true")
t.deepEqual(hasFoo("bar"), false, "false")
t.deepEqual(hasFoo("fo"), false, "false")
t.deepEqual(hasFoo("oo"), false, "false")
;t.end()})
```

This can now be run with the tape runner or ts-node:

```
$ ts-node src/hasFoo.doctest.ts | tap-diff
hasFoo
✔ true
✔ true
✔ true
✔ false
✔ false
✔ false
Done in 0.37s.

passed: 6 failed: 0 of 6 tests (171ms)

All of 6 tests passed!
```

There are four different outputs available:

* tape
* AVA
* jest
* mocha (using chai)

Pull requests for other test runners are welcome.

## Watching file changes

We can tell `doctest-ts` to watch for file changes and report which files it has written.
It tries to be a good unix citizen and thus writes the files it has created on stdout (and some info on stderr).
This makes it possible to run test runners on each line on stdout like so:

```sh
ts-node src/main.ts --watch src/hasFo.ts |
while read file; do echo running tape on $file; ts-node $file | tap-diff; done
```

Let's say we remove the ignore case `i` flag from the regex in `hasFoo`. We get this output (automatically):
```
Writing src/hasFoo.doctest.ts
running tape on src/hasFoo.doctest.ts

hasFoo
✔ true
✖ true at Test.t (src/hasFoo.doctest.ts:18:3)
[-false-][+true+]
✖ true at Test.t (src/hasFoo.doctest.ts:19:3)
[-false-][+true+]
✔ false
✔ false
✔ false

passed: 4 failed: 2 of 6 tests (264ms)

2 of 6 tests failed.
```

# License

MIT
9 changes: 9 additions & 0 deletions examples/OtherClass.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import SomeClass from "./someClass";

export default class OtherClass {

public doSomething(c: SomeClass){
return c.xyz()
}

}
32 changes: 32 additions & 0 deletions examples/someClass.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@

export default class SomeClass {

/**
* Gets the field doubled
* @example xyz
*
* import OtherClass from "./OtherClass";
*
* // Should equal 42
* SomeClass.get() // => 42
*
* SomeClass.get() + 1 // => 43
*
* new OtherClass().doSomething(new SomeClass()) // => 5
*
* const abc = 42
* SomeClass.get() // => abc
* SomeClass.get() + 1 // => abc + 1
*
*/
private static get() : number{
// a comment
// @ts-ignore
return 42
}

public xyz(){
return 5
}

}
Loading