Mock::Quick(3pm)

💖 Mock::Quick — the manual page, but make it make sense 💖

okay so bestie, this is Mock::Quick(3pm) — from the User Contributed Perl Documentation section, no less. It's giving "mock objects and classes super fast, even temporarily swap 'em out, and it's side-effect free." periodt. ✨

---

🌸 NAME 🌸

Mock::Quick — Quickly mock objects and classes, even temporarily replace them, side-effect free. 💅

---

🦋 DESCRIPTION 🦋

So like, Mock-Quick literally exists to solve the problems the other mocking libraries have. Not me being shady, it's just facts.

There are a couple mocking libraries available on CPAN. Their main problems? Verbose syntax, and — way more importantly — side-effects. Some of them expect you to mock one specific class, and then they'll unload it and redefine it. That's such a problem if all you wanted was to override a class on a lexical level, bestie. 😭

Mock-Quick gives you a declarative mocking interface that's super concise but still clear. It's got separate facilities for mocking object instances and classes. You can whip up an instance of an object with custom attributes and methods, quick quick. You can also spin up an anonymous class, optionally inheriting from another one, with literally whatever methods you want. 👑

Mock-Quick also hands you a tool that gives an OO interface for overriding methods in existing classes. That same tool lets you restore the original class methods too. And the best part? It's a localized tool — when your control object falls out of scope, the original class is restored. the way that just... works 🫶

---

✨ SYNOPSIS ✨

🎀 MOCKING OBJECTS 🎀

use Mock::Quick;

my $obj = qobj(
    foo => 'bar',            # define attribute
    do_it => qmeth { ... },  # define method
    ...
);

is( $obj->foo, 'bar' );
$obj->foo( 'baz' );
is( $obj->foo, 'baz' );

$obj->do_it();

# define the new attribute automatically
$obj->bar( 'xxx' );

# define a new method on the fly
$obj->baz( qmeth { ... });

# remove an attribute or method
$obj->baz( qclear() );

💀 STRICTER MOCK 💀

use Mock::Quick;

my $obj = qstrict(
    foo => 'bar',            # define attribute
    do_it => qmeth { ... },  # define method
    ...
);

is( $obj->foo, 'bar' );
$obj->foo( 'baz' );
is( $obj->foo, 'baz' );

$obj->do_it();

# remove an attribute or method
$obj->baz( qclear() );

Heads up: in strict mode you can no longer auto-vivify accessors and methods. So:

# Cannot define the new attribute automatically
dies_ok { $obj->bar( 'xxx' ) };

# Cannot define a new method on the fly
dies_ok { $obj->baz( qmeth { ... }) };

If you wanna add methods/accessors, you need to make a control object. That's the deal. 🎀

🧚 CONTROL OBJECTS 🧚

Control objects are objects that let you interface with a mocked object. They let you add attributes and methods, or even clear them. Lowkey unnecessary unless you're using strict mocking, or you chose not to import qmeth() and qclear().

💅 Take Control

my $control = qcontrol( $obj );

🌸 Add Attributes

$control->set_attributes(
    foo => 'bar',
    ...
);

🍓 Add Methods

$control->set_methods(
    do_it => sub { ... }, # No need to use qmeth()
    ...
);

⭐ Clear Attributes/Methods

$control->clear( qw/foo do_it .../ );

🎀 Toggle strict

$control->strict( $BOOL );

🔥 Create With Control

my $obj = qobj ...;
my $obj = qstrict ...;
my ( $obj,  $control  ) = qobjc ...;
my ( $sobj, $scontrol ) = qstrictc ...;

👑 MOCKING CLASSES 👑

Note: the control object returned here is of type Mock::Quick::Class, whereas control objects for qobj style objects are of Mock::Quick::Object::Control. Don't mix 'em up bestie.

🌈 IMPLEMENT A CLASS

This will implement a class at the namespace provided via the -implement argument. The class must not already be loaded. Once it's done, the real class will be prevented from loading until you call undefine() on the control object.

use Mock::Quick;

my $control = qclass(
    -implement => 'My::Package',

    # Insert a generic new() method (blessed hash)
    -with_new => 1,

    # Inheritance
    -subclass => 'Some::Class',
    # Can also do
    -subclass => [ 'Class::A', 'Class::B' ],

    # generic get/set attribute methods.
    -attributes => [ qw/a b c d/ ],

    # Method that simply returns a value.
    simple => 'value',

    # Custom method.
    method => sub { ... },
);

my $obj = $control->package->new;
# OR
my $obj = My::Package->new;

# Override a method
$control->override( foo => sub { ... });

# Restore it to the original
$control->restore( 'foo' );

# Remove the namespace we created, which would allow the real thing to load
# in a require or use statement.
$control->undefine();

You can also use the qimplement() method instead of qclass:

use Mock::Quick;

my $control = qimplement 'Some::Package' => ( %args );

🦋 ANONYMOUS MOCKED CLASS

This one's for when you just need to generate a class and the package name doesn't even matter. It happens when the -takeover and -implement arguments are both omitted. no name, no problem 💅

use Mock::Quick;

my $control = qclass(
    # Insert a generic new() method (blessed hash)
    -with_new => 1,

    # Inheritance
    -subclass => 'Some::Class',
    # Can also do
    -subclass => [ 'Class::A', 'Class::B' ],

    # generic get/set attribute methods.
    -attributes => [ qw/a b c d/ ],

    # Method that simply returns a value.
    simple => 'value',

    # Custom method.
    method => sub { ... },
);

my $obj = $control->package->new;

# Override a method
$control->override( foo => sub { ... });

# Restore it to the original
$control->restore( 'foo' );

# Remove the anonymous namespace we created.
$control->undefine();

🎀 TAKING OVER EXISTING/LOADED CLASSES 🎀

use Mock::Quick;

my $control = qtakeover 'Some::Package' => ( %overrides );

# Override a method
$control->override( foo => sub { ... });

# Restore it to the original
$control->restore( 'foo' );

# Destroy the control object and completely restore the original class
# Some::Package.
$control = undef;

You can also do this through qclass():

use Mock::Quick;

my $control = qclass(
    -takeover => 'Some::Package',
    %overrides
);

---

📊 METRICS 📊

All control objects have a 'metrics' method. The metrics method returns a hash where keys are method names, and values are the number of times the method has been called. When a method is altered or removed, the key is deleted. clean up after yourself, iconic behavior ✨

Metrics only apply to mocked methods. When you take over an already loaded class, metrics will only track overridden methods. iykyk

---

🫶 EXPORTS 🫶

Mock-Quick uses Exporter::Declare. This allows for exports to be prefixed or renamed. See "RENAMING IMPORTED ITEMS" in Exporter::Declare for more information.

• $obj = qobj( attribute => value, ... )
• ( $obj, $control ) = qobjc( attribute => value, ... )

Create an object. Every possible attribute works fine as a get/set accessor. You can define other methods using qmeth {...} and assigning that to an attribute. You can clear a method using qclear() as an argument.

See Mock::Quick::Object for more.

• $obj = qstrict( attribute => value, ... )
• ( $obj, $control ) = qstrictc( attribute => value, ... )

Create a stricter object, get/set accessors will not autovivify into existence for undefined attributes.

• $control = qclass( -config => ..., name => $value || sub { ... }, ... )

Define an anonymous package with the desired methods and specifications.

See Mock::Quick::Class for more.

• $control = qclass( -takeover => $package, %overrides )
• $control = qtakeover( $package, %overrides );

Take over an existing class.

See Mock::Quick::Class for more.

• $control = qimplement( $package, -config => ..., name => $value || sub { ... }, ... )
• $control = qclass( -implement => $package, ... )

Implement the given package to specifications, altering %INC so that the real class will not load. Destroying the control object will once again allow the original to load.

• qclear()

Returns a special reference that when used as an argument, will cause Mock::Quick::Object methods to be cleared.

• qmeth { my $self = shift; ... }

Define a method for an Mock::Quick::Object instance.

default_export qcontrol   => sub {
    Mock::Quick::Object::Control->new( @_ ) };

---

👑 AUTHORS 👑

Chad Granum exodist7@gmail.com

Ben Hengst notbenh@cpan.org

---

🌈 CONTRIBUTORS 🌈

Contributors are listed as authors in modules they have touched. giving credit where credit is due, as you should 💖

• Ben Hengst notbenh@cpan.org
• Glen Hinkle glen@empireenterprises.com

---

⭐ COPYRIGHT ⭐

Copyright (C) 2011 Chad Granum

Mock-Quick is free software; Standard perl licence.

Mock-Quick is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.

fr fr, no warranty. don't come for me if it breaks, that's literally what the license says. 💀

---

And that's the whole thing bestie!! 🎀 This was rendered by perl v5.34.0, dated 2022-06-15, and it's the Mock::Quick(3pm) page — slay, ate, no crumbs left ✨🦋💅