fix: expose ExecutionThreadCtx (#1043)

docs/typescript.md

@@ -59,3 +59,54 @@ declare module "testplane" {
 ```
 
 Now `testplane.ctx` will have `someVariable` typings
+
+### Extending executionContext.ctx
+
+`executionContext.ctx` is handy when you have some data specific to every test, and you want to share it across custom commands, test hooks and test body.
+
+Let's see how it works in practice.
+
+1. Let's save something to `executionContext.ctx` in `beforeEach` global hook (provided by testplane-global-hook plugin):
+   ```typescript
+   import type { TestFunctionCtx } from 'testplane';
+   import { Api } from './api';
+
+   beforeEach(async (this: TestFunctionCtx) => {
+     // Assume this is some custom command you want to run before each test
+     await this.browser.auth();
+
+     // Assume after auth we have access to a cookie needed to make requests to API
+     const sessionIdCookie = await this.getCookies(['Session_id']).then(cookies => cookies?.[0]?.value);
+     const api = new Api(sessionIdCookie);
+
+     // Now we want to make api available via executionContext.ctx
+     this.api = api;
+   })
+   ```
+
+2. Access saved data in other places:
+   ```typescript
+   // Assume we are implementing a custom command to get profile info
+   export async function getProfileInfo() {
+       const api = this.executionContext.ctx.api;
+
+       return api.getProfileInfo();
+   } 
+   ```
+
+This becomes useful when you have many commands utilising ctx. You don't need to make requests or get data over and over, you can do it once and save in ctx for future use. 
+
+Now, to make it type-safe in TypeScript, we could write the following module augmentation:
+
+```ts
+import type { TestplaneCtx } from "testplane";
+import type { Api } from './api';
+
+declare module "testplane" {
+    interface ExecutionThreadCtx {
+        api: Api;
+    }
+}
+```
+
+Now `executionContext.ctx` will include `Api` typings.

src/browser/types.ts

@@ -1,7 +1,7 @@
 import type { EventEmitter } from "events";
 import type { AssertViewCommand, AssertViewElementCommand } from "./commands/types";
 import type { BrowserConfig } from "./../config/browser-config";
-import type { ExecutionThreadToolCtx } from "../types";
+import type { ExecutionThreadCtx, ExecutionThreadToolCtx } from "../types";
 import { MoveCursorToCommand } from "./commands/moveCursorTo";
 import { OpenAndWaitCommand } from "./commands/openAndWait";
 import Callstack from "./history/callstack";
@@ -131,10 +131,7 @@ declare global {
                  * @deprecated Use `testplaneCtx` instead
                  */
                 hermioneCtx: ExecutionThreadToolCtx;
-                ctx: {
-                    browser: WebdriverIO.Browser;
-                    currentTest: Test;
-                };
+                ctx: ExecutionThreadCtx;
             };
 
             openAndWait: OpenAndWaitCommand;

src/index.ts

@@ -22,6 +22,7 @@ export type {
     TestplaneCtx,
     TestFunction,
     TestFunctionCtx,
+    ExecutionThreadCtx,
 } from "./types";
 export type { Config } from "./config";
 export type { ConfigInput, AssertViewOpts } from "./config/types";

src/types/index.ts

@@ -140,6 +140,11 @@ export interface ExecutionThreadToolCtx {
     };
 }
 
+export interface ExecutionThreadCtx {
+    browser: WebdriverIO.Browser;
+    currentTest: Test;
+}
+
 export interface TestResult extends Test {
     assertViewResults: Array<AssertViewResult>;
     description?: string;