如何高效测试LaravelScout搜索功能？sti3bas/laravel-scout-array-driver助你轻松搞定！-composer-PHP中文网

如何高效测试LaravelScout搜索功能？sti3bas/laravel-scout-array-driver助你轻松搞定！

PHPz

发布： 2025-08-21 11:36:02

原创

939人浏览过

在 Laravel 项目中，Laravel Scout 是一个非常方便的全文搜索解决方案。但当我们尝试为使用 Scout 的功能编写测试时，很快就会遇到一个痛点：测试过程中频繁地与外部搜索服务（如 Algolia 或 Elasticsearch）交互，会导致测试运行缓慢且不稳定。网络延迟、API 调用限制以及数据同步问题，都可能让你的测试变得不可靠。这不仅浪费时间，也极大地影响了开发效率。

composer在线学习地址：学习地址

痛点：真实搜索服务的测试之殇

想象一下，你正在开发一个电商网站，商品搜索是核心功能。每次你修改了商品模型，或者调整了搜索逻辑，都需要运行一系列测试来确保一切正常。如果你的测试依赖于真实的 Algolia 或 Elasticsearch 服务，那么：

速度慢如蜗牛： 每次测试都涉及网络请求和远程服务处理，测试套件运行时间急剧增加，等待测试结果成为常态。
测试不稳定： 网络中断、API 限流、外部服务故障等不可控因素，都可能导致你的测试莫名其妙地失败，让你难以分辨是代码bug还是环境问题。
环境依赖重： 本地开发和 CI/CD 环境都需要配置和维护外部搜索服务，增加了部署和集成的复杂度。
数据污染： 频繁的测试数据写入真实索引，可能导致数据混乱，影响后续开发或实际服务。

这些问题，让开发者苦不堪言，严重阻碍了测试驱动开发（TDD）的实践。那么，有没有一种方法，能让我们在不依赖真实搜索服务的情况下，快速、稳定地测试 Laravel Scout 呢？

解决方案：

sti3bas/laravel-scout-array-driver

登录后复制

登场！

答案是肯定的！得益于 Composer 强大的包管理能力和 Laravel 灵活的架构，我们可以引入

sti3bas/laravel-scout-array-driver

登录后复制

这个神器。

这个 Composer 包为 Laravel Scout 提供了一个基于数组的驱动。这意味着在测试环境中，Scout 不会再与外部搜索服务通信，而是将所有索引操作和搜索查询都模拟在内存中的一个数组里。这就像为你的搜索功能创建了一个独立的、高速的“沙盒环境”！

如何安装与配置？

使用 Composer 安装

sti3bas/laravel-scout-array-driver

登录后复制

非常简单，而且因为它只用于测试，所以我们应该将其作为开发依赖安装：

<pre class="brush:php;toolbar:false;">composer require sti3bas/laravel-scout-array-driver --dev

登录后复制

安装完成后，我们需要告诉 Laravel 在测试时使用这个数组驱动。你可以在

.env.testing

登录后复制

文件中设置：

<pre class="brush:php;toolbar:false;">SCOUT_DRIVER=array

登录后复制

或者，更推荐的做法是在

phpunit.xml

登录后复制

文件中配置，这样可以确保它只在运行 PHPUnit 测试时生效：

<pre class="brush:php;toolbar:false;"><server name="SCOUT_DRIVER" value="array"/>

登录后复制

配置完成后，当你的 PHPUnit 测试运行时，Laravel Scout 就会自动切换到

array

登录后复制

驱动，所有的搜索操作都会在内存中进行，速度飞快！

实际应用：让测试变得轻而易举

sti3bas/laravel-scout-array-driver

登录后复制

不仅提供了数组驱动，还附带了一系列方便的 PHPUnit 断言方法，让你能够轻松地检查搜索索引的状态。这些断言通过

Search

登录后复制

Facade 提供，极大简化了测试代码。

让我们看几个实际的例子：

面试猫

AI面试助手，在线面试神器，助你轻松拿Offer

查看详情

1. 检查模型是否被索引：

assertContains

登录后复制

/
assertNotContains
登录后复制

你可能想知道一个用户模型是否成功地被添加到了搜索索引中。

<pre class="brush:php;toolbar:false;">use Tests\TestCase;
use App\Models\User;
use Laravel\Scout\Search; // 注意：Search Facade

class UserSearchTest extends TestCase
{
    /** @test */
    public function a_user_can_be_indexed()
    {
        $user = User::factory()->create([
            'name' => 'Alice',
            'email' => 'alice@example.com'
        ]);

        // 默认情况下，创建模型后会自动同步到搜索索引
        Search::assertContains($user); // 断言 $user 存在于搜索索引中

        // 你也可以通过回调函数进行更精确的检查
        Search::assertContains($user, function ($record) {
            return $record['name'] === 'Alice' && $record['email'] === 'alice@example.com';
        });

        // 假设有一个用户不应该被索引
        $user2 = User::withoutSyncingToSearch(function () {
            return User::factory()->create(['name' => 'Bob']);
        });
        Search::assertNotContains($user2); // 断言 $user2 不存在于搜索索引中
    }
}

登录后复制

2. 检查索引是否为空：

assertEmpty

登录后复制

/
assertNotEmpty
登录后复制

在某些测试场景下，你可能需要确保搜索索引是空的，或者不为空。

<pre class="brush:php;toolbar:false;">use Tests\TestCase;
use App\Models\Product;
use Laravel\Scout\Search;

class ProductSearchTest extends TestCase
{
    /** @test */
    public function search_index_is_empty_initially()
    {
        Search::assertEmpty(); // 断言所有搜索索引都是空的

        Product::factory()->create(); // 创建一个产品，会自动索引

        Search::assertNotEmpty(); // 断言现在索引不为空了
        Search::assertNotEmptyIn('products'); // 断言 'products' 索引不为空
    }
}

登录后复制

3. 检查模型是否被同步：

assertSynced

登录后复制

/
assertNotSynced
登录后复制

这个断言检查模型在当前请求中是否被同步到搜索索引。它对于测试更新和删除操作后的同步行为非常有用。

<pre class="brush:php;toolbar:false;">use Tests\TestCase;
use App\Models\Post;
use Laravel\Scout\Search;

class PostSearchTest extends TestCase
{
    /** @test */
    public function post_updates_are_synced_to_search_index()
    {
        $post = Post::factory()->create(['title' => 'Initial Title']);
        Search::assertSynced($post); // 初始创建时被同步

        $post->update(['title' => 'Updated Title']); // 更新后，会被再次同步
        Search::assertSynced($post, function ($record) {
            return $record['title'] === 'Updated Title';
        });

        // 检查该模型在当前请求中是否被同步了两次 (创建一次，更新一次)
        Search::assertSyncedTimes($post, 2);
    }

    /** @test */
    public function nothing_is_synced_when_disabled()
    {
        Search::assertNothingSynced(); // 断言当前请求没有任何模型被同步

        // 使用 withoutSyncingToSearch 禁用同步
        Post::withoutSyncingToSearch(function () {
            Post::factory()->create(['title' => 'Draft Post']);
        });

        Search::assertNothingSynced(); // 确认确实没有同步
    }
}

登录后复制

4. 模拟索引记录：

fakeRecord

登录后复制

在某些高级测试场景中，你可能需要手动控制索引中的数据，而不是让 Scout 自动处理。

fakeRecord

登录后复制

方法允许你模拟一个模型的搜索索引记录。

<pre class="brush:php;toolbar:false;">use Tests\TestCase;
use App\Models\Order;
use Laravel\Scout\Search;

class OrderSearchTest extends TestCase
{
    /** @test */
    public function can_fake_search_record_data()
    {
        $order = Order::factory()->create([
            'id' => 101,
            'status' => 'pending',
            'amount' => 100.00,
        ]);

        // 默认情况下，Scout 会索引原始数据
        // $order->search()->raw()['hits'][0]['status'] 会是 'pending'

        // 模拟一个不同的状态，但只改变部分数据
        Search::fakeRecord($order, [
            'status' => 'completed',
            'processed_by' => 'admin',
        ]);

        // 现在，当通过 Scout 搜索时，会返回模拟的数据
        $record = Order::search()->where('id', 101)->raw()['hits'][0];

        $this->assertEquals('completed', $record['status']); // 模拟生效
        $this->assertEquals('admin', $record['processed_by']); // 新增字段也生效
        $this->assertEquals(100.00, $record['amount']); // 原始未覆盖的字段仍然保留
    }
}

登录后复制