Extend coverage and docs to cover alternative typed world

Author: badeball

docs/state-management.md

@@ -73,10 +73,28 @@ If you're using TypeScript, you can get optimum type safety and completion based
 
 ```ts
 interface CustomWorld extends Mocha.Context {
-  eat: (count: number) => void;
+  eat(count: number): void;
 }
 
 When("I eat {int} cucumbers", function (this: CustomWorld, count: number) {
   this.eat(count);
 });
 ```
+
+Alternatively, you can extend the default type `Mocha.Context` using a declaration file like shown below.
+
+```ts
+// declarations.d.ts
+interface CustomWorld {
+  eat(count: number): void;
+}
+
+declare namespace Mocha {
+  interface Context extends CustomWorld {}
+}
+
+// steps.ts
+When("I eat {int} cucumbers", function (count: number) {
+  this.eat(count);
+});
+```

lib/index.test-d.ts

@@ -109,6 +109,42 @@ After({ tags: "foo" }, function () {
   expectType<Mocha.Context>(this);
 });
 
+expectType<messages.GherkinDocument>(window.testState.gherkinDocument);
+expectType<messages.Pickle[]>(window.testState.pickles);
+expectType<messages.Pickle>(window.testState.pickle);
+expectType<messages.PickleStep | undefined>(window.testState.pickleStep);
+
+/**
+ * Extending world (example #1)
+ */
+interface MathWorld {
+  add(a: number, b: number): number;
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Mocha {
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface Context extends MathWorld {}
+  }
+}
+
+Given(/foo/, function () {
+  expectType<number>(this.add(1, 2));
+});
+
+When(/foo/, function () {
+  expectType<number>(this.add(1, 2));
+});
+
+Then(/foo/, function () {
+  expectType<number>(this.add(1, 2));
+});
+
+/**
+ * Extending world (example #2)
+ */
+
 interface CustomWorld extends Mocha.Context {
   pageDriver: {
     navigateTo(url: string): void;
@@ -129,8 +165,3 @@ Then(/foo/, function (this: CustomWorld, url: string) {
   expectType<CustomWorld>(this);
   this.pageDriver.navigateTo(url);
 });
-
-expectType<messages.GherkinDocument>(window.testState.gherkinDocument);
-expectType<messages.Pickle[]>(window.testState.pickles);
-expectType<messages.Pickle>(window.testState.pickle);
-expectType<messages.PickleStep | undefined>(window.testState.pickleStep);