Merge branch 'typescript-context'

Author: badeball

docs/state-management.md

@@ -65,4 +65,18 @@ When("I increment the variable by {int}", function(number) {
 Then("the variable should contain {int}", function(number) {
   expect(this.variable).to.equal(number);
 });
-````
+```
+
+## TypeScript
+
+If you're using TypeScript, you can get optimum type safety and completion based on your custom world, by setting the type of `this` in your step functions:
+
+```ts
+interface CustomWorld extends Mocha.Context {
+  eat: (count: number) => void;
+}
+
+When("I eat {int} cucumbers", function (this: CustomWorld, count: number) {
+  this.eat(count);
+});
+```

lib/diagnostics/diagnose.ts

@@ -45,12 +45,12 @@ export interface UnmatchedStep {
 
 export interface AmbiguousStep {
   step: DiagnosticStep;
-  definitions: IStepDefinition<unknown[]>[];
+  definitions: IStepDefinition<unknown[], Mocha.Context>[];
 }
 
 export interface DiagnosticResult {
   definitionsUsage: {
-    definition: IStepDefinition<unknown[]>;
+    definition: IStepDefinition<unknown[], Mocha.Context>;
     steps: DiagnosticStep[];
   }[];
   unmatchedSteps: UnmatchedStep[];
@@ -72,16 +72,18 @@ export function comparePosition(a: Position, b: Position) {
 }
 
 export function compareStepDefinition(
-  a: IStepDefinition<unknown[]>,
-  b: IStepDefinition<unknown[]>
+  a: IStepDefinition<unknown[], Mocha.Context>,
+  b: IStepDefinition<unknown[], Mocha.Context>
 ) {
   return (
     expressionToString(a.expression) === expressionToString(b.expression) &&
     comparePosition(position(a), position(b))
   );
 }
 
-export function position(definition: IStepDefinition<unknown[]>): Position {
+export function position(
+  definition: IStepDefinition<unknown[], Mocha.Context>
+): Position {
   return assertAndReturn(definition.position, "Expected to find a position");
 }
 

lib/diagnostics/index.ts

@@ -55,16 +55,18 @@ export function comparePosition(a: Position, b: Position) {
 }
 
 export function compareStepDefinition(
-  a: IStepDefinition<unknown[]>,
-  b: IStepDefinition<unknown[]>
+  a: IStepDefinition<unknown[], Mocha.Context>,
+  b: IStepDefinition<unknown[], Mocha.Context>
 ) {
   return (
     expressionToString(a.expression) === expressionToString(b.expression) &&
     comparePosition(position(a), position(b))
   );
 }
 
-export function position(definition: IStepDefinition<unknown[]>): Position {
+export function position(
+  definition: IStepDefinition<unknown[], Mocha.Context>
+): Position {
   return assertAndReturn(definition.position, "Expected to find a position");
 }
 

lib/index.test-d.ts

@@ -109,6 +109,27 @@ After({ tags: "foo" }, function () {
   expectType<Mocha.Context>(this);
 });
 
+interface CustomWorld extends Mocha.Context {
+  pageDriver: {
+    navigateTo(url: string): void;
+  };
+}
+
+Given(/foo/, function (this: CustomWorld, url: string) {
+  expectType<CustomWorld>(this);
+  this.pageDriver.navigateTo(url);
+});
+
+When(/foo/, function (this: CustomWorld, url: string) {
+  expectType<CustomWorld>(this);
+  this.pageDriver.navigateTo(url);
+});
+
+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);

lib/index.ts

@@ -54,11 +54,11 @@ export function doesFeatureMatch(expression: string): boolean {
   throw createUnimplemented();
 }
 
-export function defineStep<T extends unknown[]>(
+export function defineStep<T extends unknown[], C extends Mocha.Context>(
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   description: string | RegExp,
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  implementation: IStepDefinitionBody<T>
+  implementation: IStepDefinitionBody<T, C>
 ) {
   throw createUnimplemented();
 }
@@ -77,7 +77,9 @@ export function Step(
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-export function defineParameterType<T>(options: IParameterTypeDefinition<T>) {
+export function defineParameterType<T, C extends Mocha.Context>(
+  options: IParameterTypeDefinition<T, C>
+) {
   throw createUnimplemented();
 }
 

lib/methods.ts

@@ -19,9 +19,9 @@ import {
   IStepDefinitionBody,
 } from "./types";
 
-function defineStep<T extends unknown[]>(
+function defineStep<T extends unknown[], C extends Mocha.Context>(
   description: string | RegExp,
-  implementation: IStepDefinitionBody<T>
+  implementation: IStepDefinitionBody<T, C>
 ) {
   getRegistry().defineStep(description, implementation);
 }
@@ -34,7 +34,9 @@ function runStepDefininition(
   getRegistry().runStepDefininition(world, text, argument);
 }
 
-function defineParameterType<T>(options: IParameterTypeDefinition<T>) {
+function defineParameterType<T, C extends Mocha.Context>(
+  options: IParameterTypeDefinition<T, C>
+) {
   getRegistry().defineParameterType(options);
 }
 

lib/registry.ts

@@ -24,9 +24,9 @@ import {
 
 import { maybeRetrievePositionFromSourceMap, Position } from "./source-map";
 
-export interface IStepDefinition<T extends unknown[]> {
+export interface IStepDefinition<T extends unknown[], C extends Mocha.Context> {
   expression: Expression;
-  implementation: IStepDefinitionBody<T>;
+  implementation: IStepDefinitionBody<T, C>;
   position?: Position;
 }
 
@@ -70,7 +70,7 @@ export class Registry {
     position?: Position;
   }[] = [];
 
-  public stepDefinitions: IStepDefinition<unknown[]>[] = [];
+  public stepDefinitions: IStepDefinition<unknown[], Mocha.Context>[] = [];
 
   public beforeHooks: IHook[] = [];
 
@@ -123,11 +123,11 @@ export class Registry {
     });
   }
 
-  public defineParameterType<T>({
+  public defineParameterType<T, C extends Mocha.Context>({
     name,
     regexp,
     transformer,
-  }: IParameterTypeDefinition<T>) {
+  }: IParameterTypeDefinition<T, C>) {
     this.parameterTypeRegistry.defineParameterType(
       new ParameterType(name, regexp, null, transformer, true, false)
     );

lib/types.ts

@@ -1,15 +1,18 @@
-export interface IParameterTypeDefinition<T> {
+export interface IParameterTypeDefinition<T, C extends Mocha.Context> {
   name: string;
   regexp: RegExp;
-  transformer: (this: Mocha.Context, ...match: string[]) => T;
+  transformer: (this: C, ...match: string[]) => T;
 }
 
 export interface IHookBody {
   (this: Mocha.Context): void;
 }
 
-export interface IStepDefinitionBody<T extends unknown[]> {
-  (this: Mocha.Context, ...args: T): void;
+export interface IStepDefinitionBody<
+  T extends unknown[],
+  C extends Mocha.Context
+> {
+  (this: C, ...args: T): void;
 }
 
 export type YieldType<T extends Generator> = T extends Generator<infer R>