Test::S...:Compare(3)

📦
version 1.302027 · 2 versions
, in fedora 43

okay bestie, buckle up 🎀 this is the manual page for Test::Stream::Compare, straight out of the User Contributed Perl Documentation set. She's a classic. She's also, uh, retired. More on that in a sec 💀

✨ NAME ✨

Test::Stream::Compare — tools for comparing data structures. That's it, that's the whole vibe. 🦋

💀 DEPRECATED 💀

ngl this one hurts. This whole distribution is deprecated, and it got replaced by Test2, Test2::Suite, and Test2::Workflow. She's not coming back, bestie.

If you need to migrate, there's a whole conversion guide: peep Test::Stream::Manual::ToTest2 👑 go forth and modernize.

🌈 DESCRIPTION 🌈

This library is literally the main character energy behind is(). It's the base class for a whole lil family of comparison classes, and those are the ones that make deep structure comparisons happen. 💅

🧚 SYNOPSIS 🧚

💖 FOR COMPARISON CLASSES 💖

package Test::Stream::Compare::MyCheck;
use strict;
use warnings;

use base 'Test::Stream::Compare';
use Test::Stream::HashBase accessors => [qw/stuff/];

sub name { 'STUFF' }

sub operator {
    my $self = shift;
    my ($got) = @_;
    return 'eq';
}

sub verify {
    my $self = shift;
    my $params = @_;

    # Always check if $got even exists, this will be false if no value at
    # all was received. (as opposed to a $got of 'undef' or '0' which are
    # valid meaning this field will be true).
    return 0 unless $params{exists};

    my $got = $params{got};

    return $got eq $self->stuff;
}

🌸 FOR PLUGINS 🌸

package Test::Stream::Plugin::MyCheck;

use Test::Stream::Compare::MyCheck;

use Test::Stream::Compare qw/compare get_build push_build pop_build build/;

sub MyCheck {
    my ($got, $exp, $name, @diag) = @_;
    my $ctx = context();

    my $delta = compare($got, $exp, \&convert);

    if ($delta) {
        $ctx->ok(0, $name, [$delta->table, @diag]);
    }
    else {
        $ctx->ok(1, $name);
    }

    $ctx->release;
    return !$delta;
}

sub convert {
    my $thing = shift;
    return $thing if blessed($thing) && $thing->isa('Test::Stream::Compare::MyCheck');

    return Test::Stream::Compare::MyCheck->new(stuff => $thing);
}

🎁 EXPORTS 🎁

these are the lil goodies this module hands you 🫶

  • $delta = compare($got, $expect, \&convert) — compares the structures sitting in $got against the ones in $expect. That convert sub is your lil translator: it turns vanilla structures inside $expect into checks. And if the structures don't match up? The differences come back at you as an Test::Stream::Delta tree. 🌳
  • $build = get_build() — grab the current global build, if there even is one. 👀
  • push_build($build) — set the current global build. 💅
  • $build = pop_build($build) — unset the current global build. ⚠️ Real talk: this one throws an exception if the build you passed in isn't the same as the current global. So don't get sloppy.
  • build($class, sub { ... }) — runs that codeblock you handed over, with a fresh instance of $class as the current build. Returns the new build. ✨

🔥 METHODS 🔥

Heads up bestie: some of these you must override, others you can if you're feeling fancy. 👑

  • $dclass = $check->delta_class — returns the delta subclass that should be used. By default it's Test::Stream::Delta.
  • @deltas = $check->deltas(id => $id, exists => $bool, got => $got, convert => \&convert, seen => \%seen) — should return child deltas. 🍼
  • @lines = $check->got_lines($got) — this is your moment ✨ your chance to provide line numbers for errors in the $got structure.
  • $op = $check->operator()
  • $op = $check->operator($got) — returns the operator that was used to compare the check against the received data in $got. 🧐 And here's the trick: if there was no value for got, then there'll be no arguments at all. undef only shows up as an argument if undef was actually seen in $got — that's literally how you tell the difference between a missing value and an undefined one. iykyk 💅
  • $bool = $check->verify(id => $id, exists => $bool, got => $got, convert => \&convert, seen => \%seen) — returns true if there's a shallow match. Like, both items are arrayrefs, both items are the same string, same number, etc. ⚠️ Do not go looking deep here — deep checks live in "$check->deltas()". Stay in your lane, shallow queen. 🙈
  • $name = $check->name — gets the name of the check. 🏷️
  • $display = $check->render — what should be displayed in a table for this check, usually the name or the value. 🎀
  • $delta = $check->run(id => $id, exists => $bool, got => $got, convert => \&convert, seen => \%seen) — this is where the actual checking goes down: first a shallow check using "$check->verify", then checking "$check->deltas()". And "\%seen" is there to stop cycles from eating the whole thing. 🔁💀

🦋 SOURCE 🦋

The source code repo for Test::Stream lives at http://github.com/Test-More/Test-Stream/. Go star it or whatever, bestie. ⭐

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

🌟 AUTHORS 🌟

Chad Granum <exodist@cpan.org>

Copyright 2015 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 📜

See http://dev.perl.org/licenses/

and that's the whole page, babes 🎀 this was perl v5.42.0, dated 2025-07-25, manual page Test::Stream::Compare(3) — drink some water, hydrate, and go write some comparison classes 💖✨🦋

📦 where this page comes from