Improve docs on 'testing' a dt module (#43748)

* Improve docs on 'testing' a dt module

* Duplicate saying how you can test your tests

* Apply suggestions from code review

Co-Authored-By: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>

* Update docs with recommendations

* Apply suggestions from code review

Co-Authored-By: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>

* Changes from reviews and link from the PR template

Co-authored-by: Nathan Shively-Sanders <293473+sandersn@users.noreply.github.com>

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,6 +20,7 @@ If adding a new definition:
 If changing an existing definition:
 - [ ] Provide a URL to documentation or source code which provides context for the suggested changes: <<url here>>
 - [ ] If this PR brings the type definitions up to date with a new version of the JS library, update the version number in the header.
+- [ ] Include [tests for your changes](https://github.com/DefinitelyTyped/DefinitelyTyped#testing)
 - [ ] If you are making substantial changes, consider adding a `tslint.json` containing `{ "extends": "dtslint/dt.json" }`. If for reason the any rule need to be disabled, disable it for that line using `// tslint:disable-next-line [ruleName]` and not for whole package so that the need for disabling can be reviewed.
 
 If removing a declaration:

README.md

@@ -10,7 +10,7 @@
 
 * [Current status](#current-status)
 * [How can I contribute?](#how-can-i-contribute)
-    * [Test](#test)
+    * [Testing](#testing)
     * [Make a pull request](#make-a-pull-request)
         * [Edit an existing package](#edit-an-existing-package)
         * [Create a new package](#create-a-new-package)
@@ -112,17 +112,16 @@ You may need to add manual [references](http://www.typescriptlang.org/docs/handb
 
 Definitely Typed only works because of contributions by users like you!
 
-### Test
+### Testing
 
 Before you share your improvement with the world, use it yourself.
 
 #### Test editing an existing package
 
-To add new features you can use [module augmentation](http://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation).
-You can also directly edit the types in `node_modules/@types/foo/index.d.ts`, or copy them from there and follow the steps below.
+To test local to your app, you can use [module augmentation](http://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) to extend existing types from the DT module you want to work on.
+Alternatively, you can also edit the types directly in `node_modules/@types/foo/index.d.ts` to validate your changes, then bring the changes to this repo with the steps below.
 
-
-#### Test a new package
+#### Adding tests to a new package
 
 Add to your `tsconfig.json`:
 
@@ -131,10 +130,12 @@ Add to your `tsconfig.json`:
 "typeRoots": ["types"],
 ```
 
-(You can also use `src/types`.)
 Create `types/foo/index.d.ts` containing declarations for the module "foo".
 You should now be able to import from `"foo"` in your code and it will route to the new type definition.
 Then build *and* run the code to make sure your type definition actually corresponds to what happens at runtime.
+
+If you're wondering where to start with test code, the examples in the README of the module are a great place to start.
+
 Once you've tested your definitions with real code, make a [PR](#make-a-pull-request)
 then follow the instructions to [edit an existing package](#edit-an-existing-package) or
 [create a new package](#create-a-new-package).
@@ -167,6 +168,39 @@ First, [fork](https://guides.github.com/activities/forking/) this repository, in
 When you make a PR to edit an existing package, `dt-bot` should @-mention previous authors.
 If it doesn't, you can do so yourself in the comment associated with the PR.
 
+#### Editing tests on an existing package
+
+There should be a `[modulename]-tests.ts` file, which is considered your test file, along with any `*.ts` files it imports.
+If you don't see any test files in the module's folder, create a `[modulename]-tests.ts`.
+These files are used to validate the API exported from the `*.d.ts` files which are shipped as `@types/yourmodule`.
+
+Changes to the `*.d.ts` files should include a corresponding `*.ts` file change which shows the API being used, so that someone doesn't accidentally break code you depend on.
+If you don't see any test files in the module's folder, create a `[modulename]-tests.ts`
+
+For example, this change to a function in a `.d.ts` file adding an a new param to a function:
+
+`index.d.ts`:
+
+```diff
+- export function twoslash(body: string): string
++ export function twoslash(body: string, config?: { version: string }): string
+```
+
+`index-tests.ts`:
+```diff
+import {twoslash} from "./"
+
+// $ExpectType string
+const result = twoslash("//")
+
++ // Handle options param
++ const resultWithOptions = twoslash("//", { version: "3.7" })
++ // When the param is incorrect
++ // $ExpectError
++ const resultWithOptions = twoslash("//", {  })
+```
+
+You can validate your changes with `npm test` from the root of this repo, which takes changed files into account.
 
 #### Create a new package