@go-go-scope/testing 2.1.0 → 2.3.0

package/dist/index.d.mts

@@ -1,5 +1,97 @@
 import * as go_go_scope from 'go-go-scope';
-import { Scope, TaskOptions } from 'go-go-scope';
+import { Task, Result, Scope, TaskOptions } from 'go-go-scope';
+
+/**
+ * Assertion helpers for testing go-go-scope tasks
+ */
+
+/**
+ * Assertion result with helper methods
+ */
+interface TaskAssertion<T> {
+    /** Assert task resolves without error */
+    toResolve: () => Promise<void>;
+    /** Assert task resolves with specific value */
+    toResolveWith: (expected: T) => Promise<void>;
+    /** Assert task resolves within timeout */
+    toResolveWithin: (timeoutMs: number) => TaskAssertion<T>;
+    /** Assert task rejects with error */
+    toReject: () => Promise<void>;
+    /** Assert task rejects with specific error message */
+    toRejectWith: (message: string | RegExp) => Promise<void>;
+    /** Assert task fails with specific error type */
+    toRejectWithType: <E extends Error>(errorClass: new (...args: never[]) => E) => Promise<void>;
+    /** Get the result tuple for manual assertions */
+    result: () => Promise<Result<Error, T>>;
+}
+/**
+ * Create assertion helpers for a task.
+ *
+ * @example
+ * ```typescript
+ * import { expectTask } from '@go-go-scope/testing'
+ *
+ * test('task succeeds', async () => {
+ *   const s = scope()
+ *   await expectTask(s.task(() => Promise.resolve('done')))
+ *     .toResolveWith('done')
+ * })
+ *
+ * test('task fails', async () => {
+ *   const s = scope()
+ *   await expectTask(s.task(() => Promise.reject(new Error('fail'))))
+ *     .toRejectWith('fail')
+ * })
+ * ```
+ */
+declare function expectTask<T>(task: Task<Result<Error, T>>): TaskAssertion<T>;
+/**
+ * Assert that a task resolves successfully.
+ *
+ * @example
+ * ```typescript
+ * import { assertResolves } from '@go-go-scope/testing'
+ *
+ * test('task succeeds', async () => {
+ *   const s = scope()
+ *   const [err, result] = await assertResolves(s.task(() => Promise.resolve('done')))
+ *   expect(result).toBe('done')
+ * })
+ * ```
+ */
+declare function assertResolves<T>(task: Task<Result<Error, T>>): Promise<Result<Error, T>>;
+/**
+ * Assert that a task rejects with an error.
+ *
+ * @example
+ * ```typescript
+ * import { assertRejects } from '@go-go-scope/testing'
+ *
+ * test('task fails', async () => {
+ *   const s = scope()
+ *   const err = await assertRejects(s.task(() => Promise.reject(new Error('fail'))))
+ *   expect(err.message).toBe('fail')
+ * })
+ * ```
+ */
+declare function assertRejects<T>(task: Task<Result<Error, T>>): Promise<Error>;
+/**
+ * Assert that a task resolves within a timeout.
+ *
+ * @example
+ * ```typescript
+ * import { assertResolvesWithin } from '@go-go-scope/testing'
+ *
+ * test('task is fast', async () => {
+ *   const s = scope()
+ *   const [err, result] = await assertResolvesWithin(
+ *     s.task(() => fetchData()),
+ *     1000
+ *   )
+ * })
+ * ```
+ */
+declare function assertResolvesWithin<T>(task: Task<Result<Error, T>>, timeoutMs: number): Promise<Result<Error, T>>;
 
 /**
  * Time travel testing utilities for go-go-scope
@@ -114,28 +206,10 @@ declare function createTestScope(options?: {
     timeout?: number;
     concurrency?: number;
 }): Promise<{
-    scope: go_go_scope.Scope;
+    scope: go_go_scope.Scope<Record<string, unknown>>;
     time: TimeController;
 }>;
 
-/**
- * Test utilities for go-go-scope
- *
- * Provides helper functions and mocks for testing code that uses go-go-scope.
- *
- * @example
- * ```typescript
- * import { createMockScope } from '@go-go-scope/testing'
- *
- * const s = createMockScope({
- *   autoAdvanceTimers: true,
- *   deterministic: true
- * })
- *
- * await s.task(() => fetchData())
- * ```
- */
-
 /**
  * Options for creating a mock scope
  */
@@ -160,6 +234,8 @@ interface TaskCall {
     fn: (ctx: {
         services: Record<string, never>;
         signal: AbortSignal;
+        logger: go_go_scope.Logger;
+        context: Record<string, unknown>;
     }) => Promise<unknown>;
     options?: TaskOptions;
 }
@@ -418,5 +494,5 @@ declare function createTimeTravelController(): {
     printTimeline(): void;
 };
 
-export { assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, flushPromises };
+export { assertRejects, assertResolves, assertResolvesWithin, assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, expectTask, flushPromises };
 export type { MockChannel, MockScope, MockScopeOptions, Spy, TaskCall };

package/dist/index.mjs

@@ -1,5 +1,116 @@
 import { Scope } from 'go-go-scope';
 
+function expectTask(task) {
+  let resolvedResult;
+  let resolved = false;
+  const getResult = async () => {
+    if (!resolved) {
+      resolvedResult = await task;
+      resolved = true;
+    }
+    return resolvedResult;
+  };
+  const assertion = {
+    toResolve: async () => {
+      const [err] = await getResult();
+      if (err) {
+        throw new Error(`Expected task to resolve, but rejected: ${err.message}`);
+      }
+    },
+    toResolveWith: async (expected) => {
+      const [err, result] = await getResult();
+      if (err) {
+        throw new Error(`Expected task to resolve with ${JSON.stringify(expected)}, but rejected: ${err.message}`);
+      }
+      if (result !== expected) {
+        throw new Error(
+          `Expected task to resolve with ${JSON.stringify(expected)}, but got ${JSON.stringify(result)}`
+        );
+      }
+    },
+    toResolveWithin: (timeoutMs) => {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Task did not resolve within ${timeoutMs}ms`));
+        }, timeoutMs);
+      });
+      const racingAssertion = {
+        toResolve: async () => {
+          await Promise.race([assertion.toResolve(), timeoutPromise]);
+        },
+        toResolveWith: async (expected) => {
+          await Promise.race([assertion.toResolveWith(expected), timeoutPromise]);
+        },
+        toResolveWithin: () => racingAssertion,
+        toReject: async () => {
+          await Promise.race([assertion.toReject(), timeoutPromise]);
+        },
+        toRejectWith: async (message) => {
+          await Promise.race([assertion.toRejectWith(message), timeoutPromise]);
+        },
+        toRejectWithType: async (errorClass) => {
+          await Promise.race([assertion.toRejectWithType(errorClass), timeoutPromise]);
+        },
+        result: getResult
+      };
+      return racingAssertion;
+    },
+    toReject: async () => {
+      const [err] = await getResult();
+      if (!err) {
+        throw new Error("Expected task to reject, but resolved successfully");
+      }
+    },
+    toRejectWith: async (message) => {
+      const [err] = await getResult();
+      if (!err) {
+        throw new Error(`Expected task to reject with "${message}", but resolved successfully`);
+      }
+      const matches = typeof message === "string" ? err.message === message : message.test(err.message);
+      if (!matches) {
+        throw new Error(
+          `Expected error message "${message}", but got "${err.message}"`
+        );
+      }
+    },
+    toRejectWithType: async (errorClass) => {
+      const [err] = await getResult();
+      if (!err) {
+        throw new Error(`Expected task to reject with ${errorClass.name}, but resolved successfully`);
+      }
+      if (!(err instanceof errorClass)) {
+        throw new Error(
+          `Expected error to be instance of ${errorClass.name}, but got ${err.constructor.name}`
+        );
+      }
+    },
+    result: getResult
+  };
+  return assertion;
+}
+async function assertResolves(task) {
+  const result = await task;
+  if (result[0]) {
+    throw new Error(`Expected task to resolve, but rejected: ${result[0].message}`);
+  }
+  return result;
+}
+async function assertRejects(task) {
+  const [err] = await task;
+  if (!err) {
+    throw new Error("Expected task to reject, but resolved successfully");
+  }
+  return err;
+}
+async function assertResolvesWithin(task, timeoutMs) {
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`Task did not resolve within ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  return Promise.race([task, timeoutPromise]);
+}
+
 function createTimeController() {
   let currentTime = 0;
   const pendingTimeouts = [];
@@ -280,7 +391,8 @@ function createMockChannel() {
           if (closed || receiveIndex >= receiveValues.length) {
             return { done: true, value: void 0 };
           }
-          return { done: false, value: receiveValues[receiveIndex++] };
+          const value = receiveValues[receiveIndex++];
+          return { done: false, value };
         },
         async return() {
           return { done: true, value: void 0 };
@@ -439,4 +551,4 @@ function createTimeTravelController() {
   };
 }
 
-export { assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, flushPromises };
+export { assertRejects, assertResolves, assertResolvesWithin, assertScopeDisposed, createControlledTimer, createMockChannel, createMockScope, createSpy, createTestScope, createTimeController, createTimeTravelController, expectTask, flushPromises };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-go-scope/testing",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Testing utilities for go-go-scope - mocks, spies, and time control",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "go-go-scope": "2.1.0"
+    "go-go-scope": "2.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
@@ -49,6 +49,7 @@
     "build": "pkgroll --clean-dist",
     "lint": "biome check --write src/",
     "test": "echo 'No tests yet'",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
   }
 }