Test::Mock::Cmd(3pm)

💖 Test::Mock::Cmd 💖

okay bestie, so this is the manual page for Test::Mock::Cmd (that's the (3pm) one, a Perl module) and it is literally the tool you want when you need to fake out system(), exec() and qx() in your tests. no cap. let's get into it 🦋

---

✨ NAME ✨

Test::Mock::Cmd — mock system(), exec(), and qx() for testing 💅

---

🌸 VERSION 🌸

This doc describes Test::Mock::Cmd version 0.7.

---

🎀 SYNOPSIS 🎀

    use Test::Mock::Cmd 'system' => \&my_cmd_mocker, 'qx' => \&my_cmd_mocker;

or

    use Test::Mock::Cmd \&my_cmd_mocker;

or

    use Test::Mock::Cmd \&my_mock_system, \&my_mock_exec, \&my_mock_qx;

or

    use Test::Mock::Cmd 'system' => { X }, 'qx' =>  { X }; # can mix and match hash ref and code ref

or

    use Test::Mock::Cmd { X };

or

    use Test::Mock::Cmd { X }, { X }, { X }; # can mix and match hash ref and code ref

The typical testing usage example, coming in hot 🔥:

    use Test::More;

    our $current_system = sub { diag( explain( \@_ ) ); return 0; };
    use Test::Mock::Cmd 'system' => sub { $current_system->(@_) };

    use Foo;

    X

    {
        my $sys;
        local $current_system = sub { $sys = \@_ };

        foo(1);
        is($sys, undef, 'foo() does not call system w/ true arg');

        $sys = undef; # just in case
        foo();
        isnt($sys, undef, 'foo() calls system by default');
        is_deeply($sys, [qw(/bin/chibby -wibby foo)], 'foo() calls system with expected args);
    }

    {
        local $current_system = sub { return 0 };
        ok foo(), 'foo() returns true when system() works';
    }

    {
        local $current_system = sub { return 1 };
        ok !foo(), 'foo() returns false when system() fails';
    }

    X

    done_testing;

---

💜 DESCRIPTION 💜

So basically you get to mock system(), exec(), qx() (a.k.a. the backtick operator, a.k.a. readpipe()) with your own little functions, all so you can test code that calls them. iconic behavior ✨

Some uses might be:

1. avoid actually running the system command, just pretend we did (simulate [un]expected output, return values, etc)
2. test various return value handling (e.g. the system command core dumps how does the object handle that)
3. test that the arguments that will be passed to a system command are correct
4. simulate that really hard to reproduce low level edge case to make sure your code works correctly on affected systems
5. etc etc

---

🫶 INTERFACE 🫶

🍓 Commence mocking 🍓

Per the synopsis, you can provide import() with a hash whose keys are 'system', 'exec', or 'qx' and whose values are the code reference you want to replace the key's functionality with, 1 code reference to replace all 3 functions or 3 code references to replace system(), exec(), and qx() (in that order).

As of v0.6 you can pass in a hash instead of a coderef that will generate a handler that defaults to the original call if the first argument given is not a key in said hash.

    use Test::Mock::Cmd 'system' => {
        'git' => sub { X },
    };
    system('git', X); # calls your function
    system('whatever', X); # calls the original system

😭 Caveat 😭

Any code loaded before the mock functions are setup will retain normal system(), etc behavior. (even if the system() does not happen until much later!) yes, this is the trap, bestie, do not get got 🙈

   use X; # has functions that call system()
   use Test::Mock::Cmd ...
   use Y; # has functions that call system()
   X::i_call_system(...); # normal system() happens
   Y::i_call_system(...); # mocked system() happens

💅 Getting access to the original, un-mocked, functionality. 💅

None of these are exportable.

• Test::Mock::Cmd::orig_system() — original, not-mocked "system_LIST" in perlfunc
• Test::Mock::Cmd::orig_exec() — original, not-mocked "exec" in perlfunc
• Test::Mock::Cmd::orig_qx() — original, not-mocked "readpipe" in perlfunc

---

🌈 DIAGNOSTICS 🌈

• "Not a CODE or HASH reference" — the given value is not a code reference or a hash reference and should be one or the other. pick one, babe.
• "Key is not system, exec, or qx" — a key in your argument hash is invalid. it's giving wrong key energy 💀
• "Test::Mock::Cmd->import() requires a 1-3 key hash, 1 code/hash reference, or 3 code/hash references as arguments" — you are not passing in the required one or three arguments. the count is counting, fr fr.

---

🧚 CONFIGURATION AND ENVIRONMENT 🧚

Test::Mock::Cmd requires no configuration files or environment variables. zero. nada. clean girl aesthetic ✨

---

⭐ DEPENDENCIES ⭐

None.

---

🦋 INCOMPATIBILITIES 🦋

None reported.

---

👑 BUGS AND FEATURES 👑

Please report any bugs or feature requests (and a pull request for bonus points) through the issue tracker at <https://github.com/drmuey/p5-Test-Mock-Cmd/issues>.

---

🌸 See Also 🌸

Test::MockCommand for a more complex (and much heavier) object based approach to this.

---

💖 AUTHOR 💖

Daniel Muey "<http://drmuey.com/cpan_contact.pl>"

---

🎀 LICENCE AND COPYRIGHT 🎀

Copyright (c) 2011 cPanel, Inc. "<copyright@cpanel.net>>". All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.

---

💀 DISCLAIMER OF WARRANTY 💀

bestie this next part is in ALL CAPS on purpose, it is the legal scream, please read it, it genuinely matters 😭

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

---

and that's the whole page, bestie!! 🫶 this lil doc shipped as part of perl v5.36.0, dated 2023-01-24 — go forth and mock responsibly, you absolute main character 💅✨