// Helper function for valid context (reuse across tests) function validContext(): array { return [ 'title' => 'Test Article', 'body' => '

Test article body with enough content.

// Fake an agent with a canned response test('chat endpoint streams response', function () { $admin = User::factory()->admin()->create(); ArticleRefiner::fake(['Improved content here']);

$this->actingAs($admin)
    ->postJson('/admin/articles/ai/chat', [
        'message' => 'Improve this article',
        'context' => validContext(),
    ])->assertOk();

ArticleRefiner::assertPrompted('Improve this article');

});

// Fake an agent for quick actions test('action endpoint resolves correct agent', function () { $admin = User::factory()->admin()->create(); Proofreader::fake(['Feedback here']);

$this->actingAs($admin)
    ->postJson('/admin/articles/ai/action', [
        'action' => 'proofread',
        'context' => validContext(),
    ])->assertOk();

Proofreader::assertPrompted(fn ($prompt) =>
    str_contains($prompt->prompt, 'Review the current article')
);

});

// Generate action uses Queue::fake() instead test('generate action dispatches job', function () { Queue::fake(); $admin = User::factory()->admin()->create(); $article = Article::factory()->create();

$this->actingAs($admin)
    ->postJson('/admin/articles/ai/action', [
        'action' => 'generate',
        'article_id' => $article->id,
        'context' => validContext(),
    ])->assertAccepted();

Queue::assertPushed(ProcessArticle::class);

});

Key testing patterns:

• AgentName::fake(['response text']) — Synchronous fake with canned response
• AgentName::fake() — Empty response fake (for validation tests)
• AgentName::assertPrompted('substring') — Assert the prompt contained text
• AgentName::assertPrompted(fn ($prompt) => ...) — Assert with closure for complex matching
• Queue::fake() + Queue::assertPushed(ProcessArticle::class) — For the generate action
• $this->withoutMiddleware(ValidateCsrfToken::class) — For JSON API tests
• Conversation history tests must seed agent_conversations and agent_conversation_messages tables directly with all required JSON columns (attachments, tool_calls as empty arrays/objects)

Common Pitfalls

• Thinking-capable models crash the SDK: Avoid models like qwen3 that emit ThinkingCompleteEvent — the Laravel AI SDK doesn't handle it and throws an unrecoverable exception. Stick to llama3.2:3b or similar non-thinking models.
• Ollama, not OpenAI: Agents use #[Model('llama3.2:3b')] which runs on the Ollama Docker service. Don't confuse this with the global config('ai.default_provider') which is for different use cases. The model attribute is the Ollama model name.
• Temperature mismatches: Using high temperature (0.8) for grammar checking produces inconsistent corrections. Using low temperature (0.3) for content generation produces flat, repetitive output. Match temperature to task precision — see the spectrum table above.
• Missing context fields cause silent failures: The context array has 5 fields (title, body, excerpt, content_type, category). The body field uses ['present', 'nullable'] validation — it must be present in the request even if null. Controllers coerce null to empty string: $validated['context']['body'] = $validated['context']['body'] ?? ''.
• Forgetting to register in AgentResolver: Creating a new agent class without adding it to ACTION_AGENTS or INLINE_AGENTS in AgentResolver means it's unreachable from the controller. Also add a prompt template to ACTION_PROMPTS/INLINE_PROMPTS and update validActions()/validInlineActions().

Source: ABilenduke/copilot-developer — distributed by TomeVault.