docs: document cleanup method and introduction

docs/api.md

@@ -216,3 +216,27 @@ interface TestInstance {
 This method acts as the terminal `clear` command might on most systems. It
 allows you to clear out the buffers for `stdoutArr` and `stderrArr` - even in
 the middle of processing - in order to do more narrowed queries.
+
+# `cleanup`
+
+`SIGKILL`s processes that were spawned with render and have not halted by the end of the test.
+
+> Please note that this is done automatically if the testing framework you're using supports the `afterEach` global and it is injected to your testing environment (like mocha, Jest, and Jasmine). If not, you will need to do manual cleanups after each test.
+
+For example, if you're using the [ava](https://github.com/avajs/ava) testing framework, then you would need to use the `test.afterEach` hook like so:
+
+```javascript
+import {cleanup, render} from 'cli-testing-library'
+import test from 'ava'
+
+test.afterEach(cleanup)
+
+test('renders into document', () => {
+ render('long-running-command')
+ // ...
+})
+
+// ... more tests ...
+```
+
+Failing to call cleanup when you've called render could result in Jest failing to close due to unclosed handles and tests which are not "idempotent" (which can lead to difficult to debug errors in your tests).

docs/introduction.md

@@ -10,6 +10,8 @@ npm install --save-dev cli-testing-library
 
 - [`cli-testing-library` on GitHub](https://github.com/crutchcorn/cli-testing-library)
 
+## Table of Contents
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -46,3 +48,14 @@ will work when a real user uses it.
 
 1. A test runner or framework
 2. Specific to a testing framework (though we recommend Jest as our preference, the library works with any framework.)
+
+# Further Reading
+
+- [API reference for `render` and friends](./api.md)
+- [Jest matchers](./matchers.md)
+- [Mock user input](./user-event.md)
+- [Manually fire input events](./fire-event.md)
+- [Output matching queries](./queries.md)
+- [Debugging "CLI Testing Library" tests](./debug.md)
+- [Configure library options](./configure.md)
+- [Differences between us and other "Testing Library" projects](./differences.md)