NAME
    Test::Perinci::CmdLine - Common test suite for
    Perinci::CmdLine::{Lite,Classic,Inline}

VERSION
    This document describes version 1.483 of Test::Perinci::CmdLine (from
    Perl distribution Test-Perinci-CmdLine), released on 2023-10-30.

FUNCTIONS
  pericmd_run_ok
    Usage:

     pericmd_run_ok(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Run a single test of a Perinci::CmdLine script.

    This function is exported by default.

    Arguments ('*' denotes required arguments):

    *   argv => *array* (default: [])

        Command-line arguments that will be passed to generated CLI script.

    *   class* => *str*

        Which Perinci::CmdLine class are we testing.

    *   classic_gen_args => *hash*

        Additional arguments to be passed to
        `Perinci::CmdLine::Gen::gen_pericmd_script()`.

        Keys from this argument will be added to "gen_args" and will only be
        used when "class" is "Perinci::CmdLine::Classic".

    *   comp_answer => *array[str]*

        Test completion answer of generated CLI script.

    *   comp_line0 => *str*

        Set COMP_LINE environment for generated CLI script.

        Can contain "^" (caret) character which will be stripped from the
        final "COMP_LINE" and the position of the character will be used to
        determine "COMP_POINT".

    *   env => *hash*

        Set environment variables for generated CLI script.

    *   exit_code => *int* (default: 0)

        Expected script's exit code.

    *   exit_code_like => *re* (default: 0)

        Expected script's exit code (as regex pattern).

    *   gen_args* => *hash*

        Arguments to be passed to
        `Perinci::CmdLine::Gen::gen_pericmd_script()`.

    *   gen_status => *int* (default: 200)

        Expected generate result status.

    *   inline_allow => *array[perl::modname]*

        Modules to allow to be loaded when testing generated
        Perinci::CmdLine::Inline script.

        By default, when running the generated Perinci::CmdLine::Inline
        script, this perl option will be used (see lib::filter for more
        details):

         -Mlib::filter=allow_noncore,0

        This means the script will only be able to load core modules. But if
        the script is allowed to load additional modules, you can set this
        "inline_allow" parameter to, e.g. "["Foo::Bar","Baz"]" and the above
        perl option will become:

         -Mlib::filter=allow_noncore,0,allow,Foo::Bar;Baz

        To skip using this option, set "inline_run_filter" to false.

    *   inline_gen_args => *hash*

        Additional arguments to be passed to
        `Perinci::CmdLine::Gen::gen_pericmd_script()`.

        Keys from this argument will be added to "gen_args" and will only be
        used when "class" is "Perinci::CmdLine::Inline".

    *   inline_run_filter => *bool* (default: 1)

        Whether to use -Mfilter when running generated
        Perinci::CmdLine::Inline script.

        By default, when running the generated Perinci::CmdLine::Inline
        script, this perl option will be used (see lib::filter for more
        details):

         -Mlib::filter=allow_noncore,0,...

        This is to test that the script does not require non-core modules.
        To skip using this option (e.g. when using "pack_deps" gen option
        set to false), set this option to false.

    *   lite_gen_args => *hash*

        Additional arguments to be passed to
        `Perinci::CmdLine::Gen::gen_pericmd_script()`.

        Keys from this argument will be added to "gen_args" and will only be
        used when "class" is "Perinci::CmdLine::Lite".

    *   name => *str*

        Test name.

        If not specified, a nice default will be picked (e.g. from "argv").

    *   posttest => *code*

        Additional tests.

        For example you can do is() or ok() or other Test::More tests.

    *   stderr_like => *re*

        Test error output of generated CLI script.

    *   stderr_unlike => *re*

        Test error output of generated CLI script.

    *   stdin => *str*

        Supply stdin content to generated CLI script.

    *   stdout_like => *re*

        Test output of generated CLI script.

    *   stdout_unlike => *re*

        Test output of generated CLI script.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  pericmd_run_suite_ok
    Usage:

     pericmd_run_suite_ok(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Common test suite for Perinci::CmdLine::{Lite,Classic,Inline}.

    This function is exported by default.

    Arguments ('*' denotes required arguments):

    *   class* => *str*

        Which Perinci::CmdLine class are we testing.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  pericmd_run_test_groups_ok
    Usage:

     pericmd_run_test_groups_ok(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Run groups of Perinci::CmdLine tests.

    This function is exported by default.

    Arguments ('*' denotes required arguments):

    *   class* => *str*

        Which Perinci::CmdLine class are we testing.

    *   cleanup_tempdir => *bool*

        (No description)

    *   exclude_tags => *array[str]*

        (No description)

    *   groups* => *array*

        (No description)

    *   include_tags => *array[str]*

        (No description)

    *   tempdir => *str*

        If not specified, will create temporary directory with
        "File::Temp"'s tempdir().

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  pericmd_run_tests_ok
    Usage:

     pericmd_run_tests_ok(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Run a group of tests of a Perinci::CmdLine script.

    This function is exported by default.

    Arguments ('*' denotes required arguments):

    *   class* => *str*

        Which Perinci::CmdLine class are we testing.

    *   name => *str*

        (No description)

    *   tests* => *array[hash]*

        (No description)

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

ENVIRONMENT
  DEBUG => bool
    If set to 1, then temporary files (e.g. generated scripts for testing)
    will not be cleaned up, so you can inspect them.

  TEST_PERICMD_EXCLUDE_TAGS => str
    To set default for pericmd_ok()'s "exclude_tags" argument.

  TEST_PERICMD_INCLUDE_TAGS => str
    To set default for pericmd_ok()'s "include_tags" argument.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Test-Perinci-CmdLine>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Test-Perinci-CmdLine>.

SEE ALSO
    Supported Perinci::CmdLine backends: Perinci::CmdLine::Inline,
    Perinci::CmdLine::Lite, Perinci::CmdLine::Classic.

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2023, 2017, 2016, 2015 by perlancar
    <perlancar@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Perinci-CmdLine>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.