Test::Stream::Mock(3)

📦
version 1.302027 · 2 versions
, in fedora 43

💖 Test::Stream::Mock 💖

okay bestie, welcome to Test::Stream::Mock(3) — the User Contributed Perl Documentation page that's about to teach you how to mock classes like an absolute icon. 🎀

✨ NAME ✨

Test::Stream::Mock — module for managing mocked classes and instances. it's giving "temporarily mess with a package and then put everything back, no cap". 🦋

💀 DEPRECATED 💀

this distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow. 😭 it's not the main character anymore.

if you need to make the switch, see Test::Stream::Manual::ToTest2 for a conversion guide. 🫶

🌸 DESCRIPTION 🌸

okay so here's the vibe: this module lets you add and override methods for any package temporarily. that's it, that's the whole thing. ✨

the way that it works is — when the instance is destroyed it will restore the package to its original state. like it was never even there. ghosted, but politely. 💅

🌈 SYNOPSIS 🌈

use Test::Stream::Mock;
use MyClass;

my $mock = Test::Stream::Mock->new(
    class => 'MyClass',
    override => [
        name => sub { 'fred' },
        ...
    ],
    add => [
        is_mocked => sub { 1 }
        ...
    ],
    ...
);

# Unmock the 'name' sub
$mock->restore('name');

...

$mock = undef; # Will remove all the mocking

literally so clean. 👑

🎀 CONSTRUCTION 🎀

(yes this heading exists in the original and it's just vibing here, empty, iconic behaviour honestly)

👑 METHODS 👑

$mock = $class->new(class => $CLASS, ...)

this will create a new instance of Test::Stream::Mock that manages mocking for the specified $CLASS. 🦋

any "Test::Stream::Mock" method can be used as a constructor argument, each should be followed by an arrayref of arguments to be used with the method. for instance the 'add' method:

my $mock = Test::Stream::Mock->new(
    class => 'AClass',
    add => [foo => sub { 'foo' }],
);

is identical to this:

my $mock = Test::Stream::Mock->new(
    class => 'AClass',
);
$mock->add(foo => sub { 'foo' });

same energy, same result. 💖

$mock->add('symbol' => ..., 'synbol2' => ...)

$mock->override('symbol1' => ..., 'symbol2' => ...)

add() and override() are the primary ways to add/modify methods for a class. both accept the exact same type of arguments. the difference is that "override" will fail unless the symbol you are overriding already exists, "add" on the other hand will fail if the symbol does already exist. 💀

Note: think of override as a push operation. if you call override on the same symbol multiple times it will track that. you can use restore() as a pop operation to go back to the previous mock. "reset" can be used to remove all the mocking for a symbol.

arguments must be a symbol name, with optional sigil, followed by a new specification of the symbol. if no sigil is specified then '&' (sub) is assumed. a simple example of overriding a sub:

$mock->override(foo => sub { 'overridden foo' });
my $val = $class->foo; # Runs our override
# $val is now set to 'overridden foo'

you can also simply provide a value and it will be wrapped in a sub for you:

$mock->override( foo => 'foo' );

the example above will generate a sub that always returns the string 'foo'. ✨

there are 3 special values that can be used to generate accessors:

$mock->add(
    name => 'rw',   # Generates a read/write accessor
    age  => 'ro',   # Generates a read only accessor
    size => 'wo',   # Generates a write only accessor
);

if you want to have a sub that actually returns on of the 3 special strings, or that returns a coderef, you can use a hashref as the spec:

my $ref = sub { 'my sub' };
$mock->add(
    rw_string => { val => 'rw' },
    ro_string => { val => 'ro' },
    wo_string => { val => 'wo' },
    coderef   => { val => $ref }, # the coderef method returns $ref each time
);

you can also override/add other symbol types, such as hash:

package Foo;
...

$mock->add('%foo' => {a => 1});

print $Foo::foo{a}; # prints '1'

you can also tell mock to deduce the symbol type for the add/override from the reference, rules are similar to glob assignments:

$mock->add(
    -foo => sub { 'foo' },     # Adds the &foo sub to the package
    -foo => { foo => 1 },      # Adds the %foo hash to the package
    -foo => [ 'f', 'o', 'o' ], # Adds the @foo array to the package
    -foo => \"foo",            # Adds the $foo scalar to the package
);

no cap, that's a lot of power. 🔥

$mock->restore($SYMBOL)

restore the symbol to what it was before the last override. if the symbol was recently added this will remove it. if the symbol has been overriden multiple times this will ONLY restore it to the previous state. think of override as a push operation, this is the pop operation. 💅

$mock->reset($SYMBOL)

remove all mocking of the symbol, restore the original symbol. if the symbol was initially added then it will be completely removed. 🧚

$mock->orig($SYMBOL)

this will return the original symbol, before any mocking. for symbols that were added this will return undef. 🙈

$mock->current($SYMBOL)

this will return the current symbol. ⭐

$mock->reset_all

remove all added symbols, and restore all overriden symbols to their originals. it's a full reset bestie, everything back to factory settings. 🌈

$mock->add_constructor($NAME => $TYPE)

$mock->override_constructor($NAME => $TYPE)

this can be used to inject constructors. the first argument should be the name of the constructor. the second argument specifies the constructor type. 👑

the "hash" type is the most common, all arguments are used to create a new hash that is blessed.

hash => sub  {
    my ($class, %params) = @_;
    return bless \%params, $class;
};

the "array" type is similar to the hash type, but accepts a list instead of key/value pairs:

array => sub {
    my ($class, @params) = @_;
    return bless \@params, $class;
};

the "ref" type takes a reference and blesses it. this will modify your original input argument. ⚠️

ref => sub {
    my ($class, $params) = @_;
    return bless $params, $class;
};

the "ref_copy" type will copy your reference and bless the copy:

ref_copy => sub {
    my ($class, $params) = @_;
    my $type = reftype($params);

    return bless {%$params}, $class
        if $type eq 'HASH';

    return bless [@$params], $class
        if $type eq 'ARRAY';

    croak "Not sure how to construct an '$class' from '$params'";
};

$mock->before($NAME, sub { ... })

this will replace the orignal sub $NAME with a new sub that calls your custom code just before calling the original method. the return from your custom sub is ignored. your sub and the original both get the unmodified arguments. 🎀

$mock->after($NAME, sub { ... })

this is similar to before, except your callback runs after the original code. the return from your callback is ignored. ✨

$mock->around($NAME, sub { ... })

this gives you the chance to wrap the original sub:

$mock->around(foo => sub {
    my $orig = shift;
    my $self = shift;
    my (@args) = @_;

    ...
    $orig->(@args);
    ...

    return ...;
});

the original sub is passed in as the first argument, even before $self. you are responsible for making sure your wrapper sub returns the correct thing. no pressure bestie, but like... pressure. 😭

$mock->autoload

this will inject an "AUTOLOAD" sub into the class. this autoload will automatically generate read-write accessors for any sub called that does not already exist. 💅

$mock->block_load

this will prevent the real class from loading until the mock is destroyed. this will fail if the class is already loaded. this will let you mock a class completely without loading the original module. 🦋

$pm_file = $mock->file

this returns the relative path to the file for the module. this corresponds to the %INC entry. 🍓

$bool = $mock->purge_on_destroy($bool)

when true, this will cause the package stash to be completely obliterated when the mock object falls out of scope or is otherwise destroyed.

you do not normally want this. 💀 like genuinely, don't.

$stash = $mock->stash

this returns the stash for the class being mocked. this is the equivelent of:

my $stash = \%{"${class}\::"};

this saves you from needing to turn off strict. 🫶

$class = $mock->class

the class being mocked by this instance. 👑

$p = $mock->parent

if you mock a class twice the first instance is the parent, the second is the child. this prevents the parent from being destroyed before the child, which would lead to a very unpleasant situation. 🙈

$c = $mock->child

returns the child mock, if any. 🌸

🌟 SOURCE 🌟

the source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/. go look, it's iconic. ✨

🧚 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 bestie, no cap — this was Test::Stream::Mock(3) from perl v5.42.0, dated 2025-07-25, served fresh in your very own User Contributed Perl Documentation. slay, go mock something responsibly. 💖🦋✨

📦 where this page comes from