@llmist/testing 16.0.4 → 16.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Readable, PassThrough, Writable } from 'node:stream';
-import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, LLMStreamChunk } from 'llmist';
+import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, Skill, SkillActivation, SkillMetadata, SkillActivationOptions, ParsedSkill, LLMStreamChunk } from 'llmist';
 import { ZodType } from 'zod';
 
 /**
@@ -648,25 +648,18 @@ declare class MockBuilder {
     /**
      * Match calls to a specific model (by name, supports partial matching).
      *
-     * @example
-     * mockLLM().forModel('gpt-5')
-     * mockLLM().forModel('claude') // matches any Claude model
+     * @alias forModel
      */
     forModel(modelName: string): this;
     /**
      * Match calls to any model.
      * Useful when you want to mock responses regardless of the model used.
-     *
-     * @example
-     * mockLLM().forAnyModel()
      */
     forAnyModel(): this;
     /**
      * Match calls to a specific provider.
      *
-     * @example
-     * mockLLM().forProvider('openai')
-     * mockLLM().forProvider('anthropic')
+     * @alias forProvider
      */
     forProvider(provider: string): this;
     /**
@@ -722,6 +715,12 @@ declare class MockBuilder {
      * })
      */
     when(matcher: MockMatcher): this;
+    /**
+     * Match when any message contains an image.
+     *
+     * @alias whenMessageHasImage
+     */
+    forImage(): this;
     /**
      * Match when any message contains an image.
      *
@@ -729,6 +728,12 @@ declare class MockBuilder {
      * mockLLM().whenMessageHasImage().returns("I see an image of a sunset.")
      */
     whenMessageHasImage(): this;
+    /**
+     * Match when any message contains audio.
+     *
+     * @alias whenMessageHasAudio
+     */
+    forAudio(): this;
     /**
      * Match when any message contains audio.
      *
@@ -739,10 +744,34 @@ declare class MockBuilder {
     /**
      * Match based on the number of images in the last message.
      *
+     * @alias whenImageCount
+     */
+    withImageCount(predicate: (count: number) => boolean | number): this;
+    /**
+     * Match based on the number of images in the conversation.
+     *
      * @example
      * mockLLM().whenImageCount((n) => n >= 2).returns("Comparing multiple images...")
      */
     whenImageCount(predicate: (count: number) => boolean): this;
+    /**
+     * Return a sequence of responses. Each time the mock matches, it will return the next response in the sequence.
+     * If the sequence reaches the end, it will cycle back to the beginning.
+     *
+     * @example
+     * mockLLM().returnsSequence([
+     *   { text: 'First response' },
+     *   { text: 'Second response' }
+     * ])
+     */
+    returnsSequence(responses: MockResponse[]): this;
+    /**
+     * Set a dynamic response generator function.
+     * Equivalent to withResponse(fn).
+     *
+     * @alias withResponse
+     */
+    returnsDynamic(generator: (context: MockMatcherContext) => MockResponse | Promise<MockResponse>): this;
     /**
      * Set the text response to return.
      * Can be a static string or a function that returns a string dynamically.
@@ -1291,6 +1320,11 @@ declare class MockManager {
  * Helper function to get the global mock manager instance.
  */
 declare function getMockManager(options?: MockOptions): MockManager;
+/**
+ * Reset the global MockManager instance.
+ * Useful for clearing all mocks and state between tests.
+ */
+declare function resetMocks(): void;
 
 /**
  * Create a mock LLM stream from a mock response.
@@ -1319,6 +1353,105 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
+/**
+ * Testing utilities for skills.
+ *
+ * Provides helpers for parsing, activating, and asserting on skills
+ * without requiring filesystem setup.
+ *
+ * @module testing/skill-testing
+ */
+
+/**
+ * Parse and validate a SKILL.md content string.
+ *
+ * @param content - Full SKILL.md content (frontmatter + body)
+ * @param sourcePath - Optional source path (defaults to /test/SKILL.md)
+ * @returns Parsed skill with instructions loaded
+ *
+ * @example
+ * ```typescript
+ * import { testSkillParse } from '@llmist/testing';
+ *
+ * const parsed = testSkillParse(`---
+ * name: my-skill
+ * description: A test skill
+ * ---
+ * Do the thing.`);
+ *
+ * expect(parsed.metadata.name).toBe('my-skill');
+ * ```
+ */
+declare function testSkillParse(content: string, sourcePath?: string): ParsedSkill;
+/**
+ * Test a skill's activation with given arguments.
+ *
+ * @param skill - Skill instance to activate
+ * @param options - Activation options (arguments, cwd, etc.)
+ * @returns Activation result with resolved instructions
+ *
+ * @example
+ * ```typescript
+ * import { testSkillActivation, mockSkill } from '@llmist/testing';
+ *
+ * const skill = mockSkill({ name: 'search' });
+ * const activation = await testSkillActivation(skill, { arguments: '*.ts' });
+ * expect(activation.resolvedInstructions).toContain('*.ts');
+ * ```
+ */
+declare function testSkillActivation(skill: Skill, options?: SkillActivationOptions): Promise<SkillActivation>;
+/**
+ * Assert that a skill's resolved instructions contain expected content.
+ *
+ * @param activation - The activation result to check
+ * @param expected - Array of strings that must be present in the instructions
+ * @throws AssertionError if any expected string is missing
+ */
+declare function assertSkillContains(activation: SkillActivation, expected: string[]): void;
+/**
+ * Validate a SKILL.md content string and return any issues.
+ *
+ * @param content - Full SKILL.md content
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateSkill(content: string): string[];
+/**
+ * Create a mock Skill instance for testing.
+ *
+ * @param overrides - Override any metadata fields
+ * @param instructions - Custom instructions body
+ */
+declare function mockSkill(overrides?: Partial<SkillMetadata>, instructions?: string): Skill;
+/**
+ * Fluent builder for creating test skills.
+ *
+ * @example
+ * ```typescript
+ * import { MockSkillBuilder } from '@llmist/testing';
+ *
+ * const skill = new MockSkillBuilder()
+ *   .withName('gmail-read')
+ *   .withDescription('Read Gmail messages')
+ *   .withInstructions('Use gws to read emails.')
+ *   .build();
+ * ```
+ */
+declare class MockSkillBuilder {
+    private _name;
+    private _description;
+    private _instructions;
+    private _overrides;
+    withName(name: string): this;
+    withDescription(description: string): this;
+    withInstructions(instructions: string): this;
+    withModel(model: string): this;
+    withContext(context: "fork" | "inline"): this;
+    withPaths(paths: string[]): this;
+    withAllowedTools(tools: string[]): this;
+    withGadgets(gadgets: string[]): this;
+    build(): Skill;
+}
+
 /**
  * Stream testing utilities for llmist.
  * Provides helpers for creating and consuming test streams.
@@ -1419,4 +1552,43 @@ declare function createEmptyStream(): LLMStream;
  */
 declare function createErrorStream(chunksBeforeError: LLMStreamChunk[], error: Error): LLMStream;
 
-export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, type MockStats, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, testGadget, testGadgetBatch, waitFor };
+/**
+ * Mock TUI App interface.
+ */
+interface MockTUIApp {
+    setProfiles: any;
+    setFocusMode: any;
+    startWaitingForPrompt: any;
+    destroy: any;
+    onQuit: any;
+    onCancel: any;
+    showLLMCallStart: any;
+    updateStreamingTokens: any;
+    clearRetry: any;
+    showThrottling: any;
+    addSystemMessage: any;
+    clearThrottling: any;
+    showRetry: any;
+    showApproval: any;
+    waitForInput: any;
+    subscribeToTree: any;
+    handleEvent: any;
+    addGadgetCost: any;
+    flushText: any;
+    resetAbort: any;
+    startNewSession: any;
+    showUserMessage: any;
+    clearPreviousSession: any;
+    clearStatusBar: any;
+    onMidSessionInput: any;
+    waitForPrompt: any;
+    getAbortSignal: any;
+}
+/**
+ * Creates a mock TUI app for testing.
+ *
+ * NOTE: This currently uses Vitest's `vi` for mocks.
+ */
+declare const createMockTUIApp: () => MockTUIApp;
+
+export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, MockSkillBuilder, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, assertSkillContains, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, mockSkill, resetMocks, testGadget, testGadgetBatch, testSkillActivation, testSkillParse, validateSkill, waitFor };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Readable, PassThrough, Writable } from 'node:stream';
-import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, LLMStreamChunk } from 'llmist';
+import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, Skill, SkillActivation, SkillMetadata, SkillActivationOptions, ParsedSkill, LLMStreamChunk } from 'llmist';
 import { ZodType } from 'zod';
 
 /**
@@ -648,25 +648,18 @@ declare class MockBuilder {
     /**
      * Match calls to a specific model (by name, supports partial matching).
      *
-     * @example
-     * mockLLM().forModel('gpt-5')
-     * mockLLM().forModel('claude') // matches any Claude model
+     * @alias forModel
      */
     forModel(modelName: string): this;
     /**
      * Match calls to any model.
      * Useful when you want to mock responses regardless of the model used.
-     *
-     * @example
-     * mockLLM().forAnyModel()
      */
     forAnyModel(): this;
     /**
      * Match calls to a specific provider.
      *
-     * @example
-     * mockLLM().forProvider('openai')
-     * mockLLM().forProvider('anthropic')
+     * @alias forProvider
      */
     forProvider(provider: string): this;
     /**
@@ -722,6 +715,12 @@ declare class MockBuilder {
      * })
      */
     when(matcher: MockMatcher): this;
+    /**
+     * Match when any message contains an image.
+     *
+     * @alias whenMessageHasImage
+     */
+    forImage(): this;
     /**
      * Match when any message contains an image.
      *
@@ -729,6 +728,12 @@ declare class MockBuilder {
      * mockLLM().whenMessageHasImage().returns("I see an image of a sunset.")
      */
     whenMessageHasImage(): this;
+    /**
+     * Match when any message contains audio.
+     *
+     * @alias whenMessageHasAudio
+     */
+    forAudio(): this;
     /**
      * Match when any message contains audio.
      *
@@ -739,10 +744,34 @@ declare class MockBuilder {
     /**
      * Match based on the number of images in the last message.
      *
+     * @alias whenImageCount
+     */
+    withImageCount(predicate: (count: number) => boolean | number): this;
+    /**
+     * Match based on the number of images in the conversation.
+     *
      * @example
      * mockLLM().whenImageCount((n) => n >= 2).returns("Comparing multiple images...")
      */
     whenImageCount(predicate: (count: number) => boolean): this;
+    /**
+     * Return a sequence of responses. Each time the mock matches, it will return the next response in the sequence.
+     * If the sequence reaches the end, it will cycle back to the beginning.
+     *
+     * @example
+     * mockLLM().returnsSequence([
+     *   { text: 'First response' },
+     *   { text: 'Second response' }
+     * ])
+     */
+    returnsSequence(responses: MockResponse[]): this;
+    /**
+     * Set a dynamic response generator function.
+     * Equivalent to withResponse(fn).
+     *
+     * @alias withResponse
+     */
+    returnsDynamic(generator: (context: MockMatcherContext) => MockResponse | Promise<MockResponse>): this;
     /**
      * Set the text response to return.
      * Can be a static string or a function that returns a string dynamically.
@@ -1291,6 +1320,11 @@ declare class MockManager {
  * Helper function to get the global mock manager instance.
  */
 declare function getMockManager(options?: MockOptions): MockManager;
+/**
+ * Reset the global MockManager instance.
+ * Useful for clearing all mocks and state between tests.
+ */
+declare function resetMocks(): void;
 
 /**
  * Create a mock LLM stream from a mock response.
@@ -1319,6 +1353,105 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
+/**
+ * Testing utilities for skills.
+ *
+ * Provides helpers for parsing, activating, and asserting on skills
+ * without requiring filesystem setup.
+ *
+ * @module testing/skill-testing
+ */
+
+/**
+ * Parse and validate a SKILL.md content string.
+ *
+ * @param content - Full SKILL.md content (frontmatter + body)
+ * @param sourcePath - Optional source path (defaults to /test/SKILL.md)
+ * @returns Parsed skill with instructions loaded
+ *
+ * @example
+ * ```typescript
+ * import { testSkillParse } from '@llmist/testing';
+ *
+ * const parsed = testSkillParse(`---
+ * name: my-skill
+ * description: A test skill
+ * ---
+ * Do the thing.`);
+ *
+ * expect(parsed.metadata.name).toBe('my-skill');
+ * ```
+ */
+declare function testSkillParse(content: string, sourcePath?: string): ParsedSkill;
+/**
+ * Test a skill's activation with given arguments.
+ *
+ * @param skill - Skill instance to activate
+ * @param options - Activation options (arguments, cwd, etc.)
+ * @returns Activation result with resolved instructions
+ *
+ * @example
+ * ```typescript
+ * import { testSkillActivation, mockSkill } from '@llmist/testing';
+ *
+ * const skill = mockSkill({ name: 'search' });
+ * const activation = await testSkillActivation(skill, { arguments: '*.ts' });
+ * expect(activation.resolvedInstructions).toContain('*.ts');
+ * ```
+ */
+declare function testSkillActivation(skill: Skill, options?: SkillActivationOptions): Promise<SkillActivation>;
+/**
+ * Assert that a skill's resolved instructions contain expected content.
+ *
+ * @param activation - The activation result to check
+ * @param expected - Array of strings that must be present in the instructions
+ * @throws AssertionError if any expected string is missing
+ */
+declare function assertSkillContains(activation: SkillActivation, expected: string[]): void;
+/**
+ * Validate a SKILL.md content string and return any issues.
+ *
+ * @param content - Full SKILL.md content
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateSkill(content: string): string[];
+/**
+ * Create a mock Skill instance for testing.
+ *
+ * @param overrides - Override any metadata fields
+ * @param instructions - Custom instructions body
+ */
+declare function mockSkill(overrides?: Partial<SkillMetadata>, instructions?: string): Skill;
+/**
+ * Fluent builder for creating test skills.
+ *
+ * @example
+ * ```typescript
+ * import { MockSkillBuilder } from '@llmist/testing';
+ *
+ * const skill = new MockSkillBuilder()
+ *   .withName('gmail-read')
+ *   .withDescription('Read Gmail messages')
+ *   .withInstructions('Use gws to read emails.')
+ *   .build();
+ * ```
+ */
+declare class MockSkillBuilder {
+    private _name;
+    private _description;
+    private _instructions;
+    private _overrides;
+    withName(name: string): this;
+    withDescription(description: string): this;
+    withInstructions(instructions: string): this;
+    withModel(model: string): this;
+    withContext(context: "fork" | "inline"): this;
+    withPaths(paths: string[]): this;
+    withAllowedTools(tools: string[]): this;
+    withGadgets(gadgets: string[]): this;
+    build(): Skill;
+}
+
 /**
  * Stream testing utilities for llmist.
  * Provides helpers for creating and consuming test streams.
@@ -1419,4 +1552,43 @@ declare function createEmptyStream(): LLMStream;
  */
 declare function createErrorStream(chunksBeforeError: LLMStreamChunk[], error: Error): LLMStream;
 
-export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, type MockStats, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, testGadget, testGadgetBatch, waitFor };
+/**
+ * Mock TUI App interface.
+ */
+interface MockTUIApp {
+    setProfiles: any;
+    setFocusMode: any;
+    startWaitingForPrompt: any;
+    destroy: any;
+    onQuit: any;
+    onCancel: any;
+    showLLMCallStart: any;
+    updateStreamingTokens: any;
+    clearRetry: any;
+    showThrottling: any;
+    addSystemMessage: any;
+    clearThrottling: any;
+    showRetry: any;
+    showApproval: any;
+    waitForInput: any;
+    subscribeToTree: any;
+    handleEvent: any;
+    addGadgetCost: any;
+    flushText: any;
+    resetAbort: any;
+    startNewSession: any;
+    showUserMessage: any;
+    clearPreviousSession: any;
+    clearStatusBar: any;
+    onMidSessionInput: any;
+    waitForPrompt: any;
+    getAbortSignal: any;
+}
+/**
+ * Creates a mock TUI app for testing.
+ *
+ * NOTE: This currently uses Vitest's `vi` for mocks.
+ */
+declare const createMockTUIApp: () => MockTUIApp;
+
+export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, MockSkillBuilder, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, assertSkillContains, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, mockSkill, resetMocks, testGadget, testGadgetBatch, testSkillActivation, testSkillParse, validateSkill, waitFor };