assertDatabaseHasOnly Test Convenience Function

[GavG]

In my unit tests, I frequently invoke some functionality which results in a record being created, which I then verify has been stored and that it was the only record stored in the given table.

I have ample test functions with assertion pairs like these:

$this->assertEquals(1, Model::count());
$this->assertDatabaseHas(['data' => $model_data]);

This works fine, although it results in 2 queries (where it could be achieved with just 1) and I have to remember to include the assertEquals 1 count call every time (which I sometimes forget).

So, I wrote a convenience function: assertDatabaseHasOnly

This function asserts that "the table contains exactly one row total, and that row matches these attributes".

Usage:

$this->assertDatabaseHasOnly(['data' => $model_data]);

My current implementation extends the HasInDatabase, and changes the matches function to be:

    /**
     * Check if only this data is found in the given table.
     *
     * @param  string  $table
     * @return bool
     */
    public function matches($table): bool
    {
        $query = $this->database->table($table)
            ->where($this->data)
            ->whereRaw(
                sprintf(
                    '(select count(*) from %s) = 1',
                    $this->database->getQueryGrammar()->wrapTable($table),
                ),
            );

        return $query->exists();
    }

Producing a query that looks like this:

select * from `model_table` where (`data` = ?) and (select count(*) from `model_table`) = 1

My question to the audience is: Is this at all a useful idea for a convenience function or just fluff and not framework worthy?

Thanks

[Pola5h]

This is a genuinely useful addition! The use case is very common in feature tests, verifying both the content and uniqueness of a record in one assertion.

A small concern with the current implementation, the subquery approach works, but it runs two logical checks in one SQL query, which can be harder to debug when the assertion fails. You won't know why it failed, was it the data mismatch or the count?

A slightly more debuggable implementation:

public function assertDatabaseHasOnly(string $table, array $data, string $connection = null): void
{
    $this->assertDatabaseCount($table, 1);
    $this->assertDatabaseHas($table, $data);
}

This approach:

• Reuses existing assertion methods (no new DB constraint logic)
• Gives clearer failure messages, you know exactly which assertion failed
• Still reduces it to a single method call at the test level
• Is easier to maintain

Regarding framework worthiness, I'd say yes, with one naming consideration. assertDatabaseHasOnly could be misread as "the table has only these columns". A slightly clearer name might be:

assertDatabaseHasExactlyOne(string $table, array $data)
assertDatabaseHasSingleRow(string $table, array $data)

But assertDatabaseHasOnly still reads naturally in context. Overall, this is a clean, practical DX improvement that fits well alongside assertDatabaseHas, assertDatabaseCount, and assertDatabaseMissing.

[GavG]

Thanks for the well structured feedback 👍

I had considered the concerns about debugging, but I think these can be handled with subsequent checks if needed. This keeps the efficiency gain for the success case.

As for the naming convention, I had also mulled on this. "Only" is used here and there throughout Laravel, but perhaps not always in a consistent way. So maybe something more explicit like "ExactlyOne" is more apt, but I feel it lacks the notion that the match is the only / sole row, "exact" seems to imply exact matching (rather than lose).

I think "Row" in the function name is redundant, and doesn't fit with existing similar test functions.

"Single" or "Sole" could be good candidates, but this can be worked out if sufficient positive concensus if achieved on the idea first 😂

[shaedrich]

"Sole" sounds like a good idea 👍🏻

[shaedrich]

Maybe, this should be wrapped in a broader method:

public function assertDatabaseHasCount(string $table, array $data, int $count = 1, string $connection = null): void
{
    $this->assertDatabaseCount($table, $count);
    $this->assertDatabaseHas($table, $data);
}

[GavG]

Thanks for the feedback. I had thought about this, or even about allowing the function to take in an array/variadic list of records to check. The implementation would then count these and ensure that matches.

However, looking at my codebase, I'd very rarely encounter such use case.

But perhaps others have such frequent use cases? Or it's worth adding in any case for posterity.