File Coverage

=head1 NAME

Test::Log::Abstraction - Capture log output in tests and assert on it

=head1 VERSION

0.002.0

=head1 SYNOPSIS

=head2 Check what your code logged

    use Test::Most;
    use Test::Log::Abstraction;

    # Give the test logger to the code that you are testing
    my $logger = Test::Log::Abstraction->new();
    my $obj = Some::Class->new(logger => $logger);

    $obj->do_something();

    # Each of these is one TAP test
    $logger->like(qr/updated/, 'do_something() logs that it updated');
    $logger->has_level('error', 'an error was logged');
    $logger->unlike(qr/fatal/, 'nothing fatal was logged');
    is($logger->count(), 3, 'three messages were logged');

    done_testing();

=head2 Check that nothing was logged

    my $logger = Test::Log::Abstraction->new();
    Some::Class->new(logger => $logger)->run();
    $logger->empty('a normal run logs nothing');

=head2 Test several steps with one logger

    my $logger = Test::Log::Abstraction->new();
    my $obj = Some::Class->new(logger => $logger);

    $obj->load('good.csv');
    $logger->empty('good file: no messages');

    $logger->clear();    # forget the messages from the first step
    $obj->load('bad.csv');
    $logger->has_level('warn', 'bad file: a warning');

=head2 Look at the messages yourself

    foreach my $entry (@{ $logger->messages() }) {
        print "$entry->{level}: $entry->{message}\n";
    }

    # Structured fields, from a call such as
    # $logger->info('user logged in', { user => 'alice' })
    is($logger->messages()->[0]->{fields}->{user}, 'alice', 'user field');

=head2 Control what is printed while the test runs

    # Print nothing (the messages are still captured)
    my $quiet = Test::Log::Abstraction->new(diag => 'none');

    # Print everything
    my $loud = Test::Log::Abstraction->new(verbose => 1);

    # Print only errors and more serious messages
    my $errors = Test::Log::Abstraction->new(diag => 'error');

=head2 Test code that checks the log level

    # The code under test does: if($logger->is_debug()) { ... }
    my $logger = Test::Log::Abstraction->new(level => 'warning');
    ok(!$logger->is_debug(), 'debug output is turned off');

=head2 Get this module's own messages in another language

    my $logger = Test::Log::Abstraction->new(lang => 'de');    # German
    my $french = Test::Log::Abstraction->new(country => 'FR');    # French

=head1 DESCRIPTION

=head2 What this module is

Some code writes log messages through a logger object.  In production that
object is usually a L<Log::Abstraction> logger.  In a test, you give the code
a C<Test::Log::Abstraction> object instead.

This object does not write the messages to a file.  It keeps them in a list
in memory.  After the code has run, your test can check the list: was a
message logged, at which level, and what did it say?

It never writes to disk, and it does not load any logging backend.

=head2 Which methods it has

=over 4

=item * B<Log levels.>  The level methods of L<Log::Abstraction>:
C<trace>, C<debug>, C<info>, C<notice>, C<warn>, C<error>, C<fatal>,
C<critical>, C<alert> and C<emergency>.  It also accepts the syslog names
C<warning>, C<err>, C<crit>, C<emerg>, C<panic> and C<informational>.

=item * B<Other logger methods.>  C<level()>, C<is_debug()> and the other
C<is_E<lt>levelE<gt>()> methods, C<messages()> and C<flush()>.  Code under
test may call these, so they work as they do in L<Log::Abstraction>.

=item * B<Test methods.>  C<like>, C<unlike>, C<has_level> and C<empty>.
Each one reports one test result, like C<ok()> in L<Test::More>.

=item * B<Helper methods.>  C<count>, C<clear>, C<verbose> and C<lang>.

=back

=head2 Which messages are printed

Every message is always stored.  This section is only about which messages
are also printed in the test output, as TAP comments (lines that start with
C<#>).

By default, C<warning> and more serious levels are printed.  So if a test
causes a warning by accident, you see it.  C<trace>, C<debug>, C<info> and
C<notice> messages are not printed.

Verbose mode prints every message.  Verbose mode is on when you pass
C<< verbose => 1 >> to C<new()>.  If you do not pass C<verbose>, it is on
when the environment variable C<TEST_VERBOSE> is true (C<prove -v> sets
it), or when C<VERBOSE> is true.

To choose the levels, use the C<diag> option of C<new()>:

=over 4

=item * C<'all'> - print every message.

=item * C<'none'> - print nothing (verbose mode still prints everything).

=item * A level name, such as C<'error'> - print that level and every more
serious level.

=item * A list, such as C<['info', 'error']> - print only these levels.

=back

Put exactly: a message is printed when B<any one> of these is true, and
not otherwise:

=over 4

=item 1. Verbose mode is on.

=item 2. C<diag> is C<'all'>.

=item 3. C<diag> is a list, and the message's level name is in it.

=item 4. C<diag> is a level name, the message's level is a known level, and
its number is the same as, or lower than, that level's number.

=back

So a misspelt level (caught by L</AUTOLOAD>) is printed only by rules 1 to
3; and C<'none'> or an empty list means only rule 1 can apply.

When a test method fails, the messages that explain the failure are printed
under it.  So you can see why it failed without running the test again.

=head2 Global variables are left alone

No method changes C<$@>, C<$!> or C<$_>, and none of them touches an
C<alarm()> timer.  So you can log, or test the log, inside an error
handler, and C<$@> still holds the error afterwards.  (A method that stops
with an error does set C<$@>, as every Perl error does.)

=head2 Levels and how serious they are

Each level has a number.  A lower number means a more serious message.
These are the syslog numbers.

    0  emergency, emerg, panic
    1  alert
    2  critical, crit, fatal
    3  error, err
    4  warning, warn
    5  notice
    6  info, informational
    7  debug, trace

=head2 Language of this module's messages

This module has its own messages: error messages, warnings, and the text
that explains a failed test.  They can be in English (C<en>), German
(C<de>), French (C<fr>) or Simplified Chinese (C<zh>).

The language is chosen like this.  The first rule that gives an answer is
used:

=over 4

=item 1. The C<lang> option, for example C<< lang => 'de' >>.

=item 2. The C<country> option, a two-letter country code such as C<'FR'>.

=item 3. Only when C<< lang => 'auto' >>: the environment variables
C<LC_ALL>, C<LC_MESSAGES> and C<LANG>, in that order.

=item 4. C<$Test::Log::Abstraction::config{lang}>, which is C<'en'>.

=back

The default is English, not the language of your computer.  This is on
purpose: the test output is then the same on every computer.

If a message has no translation, the English message is used.  You can add
or change messages with the C<i18n> option of C<new()>.

This only changes this module's own messages.  The messages that your code
logs are never changed.

=head2 Default settings

The defaults for C<new()> are in the hash
C<%Test::Log::Abstraction::config>.  It has the same keys as the options of
C<new()>.  You can change it in a test, or fill it with
L<Object::Configure>:

    $Test::Log::Abstraction::config{'diag'} = 'none';

A change only affects loggers that are created after it.

You can also pass the result of L<Object::Configure> straight to C<new()>.
Settings in environment variables named C<Test__Log__Abstraction__KEY>
then override the arguments; the extra keys that L<Object::Configure>
adds (such as its own C<logger>) are ignored:

    # In the shell: export Test__Log__Abstraction__diag=none
    my $params = Object::Configure::configure('Test::Log::Abstraction', { level => 'error' });
    my $logger = Test::Log::Abstraction->new($params);

=head1 COMMON PITFALLS

=over 4

=item * B<The test methods are tests.>  C<like>, C<unlike>, C<has_level>
and C<empty> each add one test to the TAP output.  If you give a test
plan (C<< tests => 5 >>), count them.  Or use C<done_testing()>.

=item * B<Messages from earlier steps are still there.>  A logger keeps
every message until you call C<clear()>.  If one logger is used for
several steps, C<like> may match a message from an earlier step.

=item * B<A string pattern is a regular expression.>  C<like('a.c')>
matches C<'abc'>, because C<.> means "any character".  To match the text
exactly, use C<qr/\Qa.c\E/>.

=item * B<Different names for one level are counted apart.>  C<warn> and
C<warning> have the same number, but C<count('warn')> and
C<has_level('warn')> do not see messages logged with C<warning()>.  Check
the name that the code under test uses.  C<fatal> is stored as C<fatal>,
but L<Log::Abstraction> stores it as C<error>.

=item * B<C<undef> is not the same as "no value".>

=over 4

=item * An C<undef> argument to a level method becomes the text
C<undef> in the message.  (L<Log::Abstraction> drops it.)

=item * C<< verbose => undef >> turns verbose mode B<off>.  To use the
environment variables instead, do not pass C<verbose> at all.

=item * C<< diag => undef >> and C<< level => undef >> use the default
from C<%config>.

=item * C<count(undef)> counts all messages.  C<level(undef)> returns the
level number and changes nothing.

=item * C<like(undef)>, C<unlike(undef)> and C<has_level(undef)> stop the
test with an error.

=back

=item * B<One hash reference, or a hash reference at the end.>
C<< $logger->info({ a => 1 }) >> logs the text C<{a =E<gt> 1}>.  But
C<< $logger->info('text', { a => 1 }) >> logs the text C<text> and stores
C<< { a => 1 } >> in C<fields>.  An empty hash at the end is dropped.

=item * B<Copies are shallow (only one level deep).>

=over 4

=item * When a message has C<fields>, the fields hash is copied.  But a
hash or array B<inside> the fields is not copied.  If your code changes it
later, the stored message changes too.  And if the fields contain the
logger itself, the logger is never freed (a reference cycle) until you
call C<clear()>.

=item * C<messages()> returns a new list, but the entries in it are the
stored entries.  Do not change them, unless you want to change what was
captured.

=item * C<new()> keeps its own copy of the C<diag> list and the C<i18n>
tables.  Changing your array or hash afterwards does not change the
logger.  (A part of an C<i18n> table that contains itself is left out of
the copy; it would only ever render as an empty string.)

=item * When you clone a logger with C<< $logger->new(%options) >>, each
option replaces the old option completely.  For example,
C<< $logger->new(i18n => { de => {...} }) >> replaces the whole C<i18n>
hash.  The translations in the old hash are not kept.

=back

=item * B<The C<i18n> option is merged message by message.>  You only
need to give the messages that you want to change.  For each message,
this module looks in your C<i18n> hash first, and then in its own list.
So any message that you do not give keeps its normal text.

=item * B<A misspelt method name does not stop the test.>
C<< $logger->wran('x') >> stores the message under the name C<wran> and
prints a notice.  The test still passes, unless you check the messages.

=item * B<C<prove -v> prints everything.>  C<prove -v> sets
C<TEST_VERBOSE>, which turns verbose mode on.  If a test checks what is
printed, set C<< verbose => 0 >> or C<$ENV{TEST_VERBOSE} = 0>.

=item * B<C<level()> does not hide messages.>  It only changes the answers
of the C<is_*> methods.  Every message is still stored.

=back

=head1 ENCODING

This module never changes the text that your code logs.  It stores each
message exactly as it was given.

=over 4

=item * B<Log messages and fields: any text.>  ASCII, other languages and
emoji are all stored safely.  It does not matter if the text is a Perl
character string (decoded, for example with C<use utf8> or
L<Encode/decode>) or a byte string (for example, UTF-8 bytes read from a
file).

=item * B<Matching with C<like> and C<unlike>.>  The pattern is matched
against the stored text as it is.  So the pattern and the message must be
the same kind of string.  A pattern with a character, such as
C<qr/\x{1F600}/>, does not match the same emoji stored as UTF-8 bytes.

=item * B<Printed messages.>  A Perl character string that has any
character above ASCII is printed as UTF-8.  A byte string is printed
unchanged.  Perl cannot always see the difference: a string that was not
decoded, and has no character above 255 (such as C<"caf\x{e9}">), is
treated as bytes.  If the output already has an encoding layer (for example, set
by L<Test2::Plugin::UTF8>), the text is not encoded again.

=item * B<This module's own messages.>  German, French and Chinese messages
are character strings, and they are printed as UTF-8.  There is one
problem case: a translated message that includes a logged message that is
a non-ASCII byte string.  That part of the text is printed wrongly (it is
encoded twice).  English messages do not have this problem.

=item * B<Options.>  C<lang> and C<country> must be ASCII, in the formats
given under L</new>.  Level names are ASCII.  Templates in the C<i18n>
option may contain any characters, but placeholder names must be ASCII
letters, digits or C<_>.

=item * B<Test names.>  Test names are passed to L<Test::Builder>
unchanged.

=back

=cut

=head1 METHODS

=head2 new

Create a new test logger.

=head3 Purpose

Make a logger that stores every message it is given, so that your test can
check the messages later.

=head3 Args

All options are optional.  Give them as a list (C<< key => value >>) or as
one hash reference.

=over 4

=item * C<verbose> - true: print every message.  False: use the C<diag>
rule.  If you do not give it, the value of C<$ENV{TEST_VERBOSE}> or
C<$ENV{VERBOSE}> is used.

=item * C<diag> - which messages to print.  C<'all'>, C<'none'>, a level
name (print that level and every more serious level), or an array
reference of level names.  Upper or lower case does not matter.  The
default is C<'warning'>.

=item * C<level> - the level that C<level()> and the C<is_*> methods
report.  The default is C<'trace'>, so every C<is_*> method returns 1, and
the code under test runs all its debug code.  This option does not stop
any message from being stored.

=item * C<lang> - the language of this module's own messages: C<'en'>,
C<'de'>, C<'fr'>, C<'zh'>, a locale name such as C<'de_DE.UTF-8'>, or
C<'auto'> (read the environment).  Must be 2 or 3 ASCII letters, then
optionally C<_>, C<.>, C<@> or C<-> and more text.

=item * C<country> - a two-letter country code such as C<'GB'> or
C<'fr'> (upper or lower case).  Used to choose the language when C<lang>
is not given.

=item * C<i18n> - your own message texts, as
C<< { language => { message_key => template } } >>.  See L</i18n>.

=back

Other options are allowed and ignored.  (A L<Log::Abstraction>
configuration hash can be passed unchanged.)  If you pass an odd number of
arguments, they are all ignored.

=head3 Three ways to call it

=over 4

=item * C<< Test::Log::Abstraction->new(%options) >> - the usual way.

=item * C<< $logger->new(%options) >> - make a B<clone>: a new logger with
the same options, the same C<verbose> and C<level> settings, and a copy of
the stored messages.  The options that you pass replace the old ones.

=item * C<Test::Log::Abstraction::new(%options)> - called as a function.
This works too.

=back

=head3 Returns

The new logger object.

=head3 Side Effects

Reads C<%ENV> to decide on verbose mode, and, with C<< lang => 'auto' >>,
to choose the language.  Nothing else changes.  A clone does not change the
original logger.

=head3 EXAMPLE

    # The usual way
    my $logger = Test::Log::Abstraction->new();

    # Store everything, print nothing
    my $quiet = Test::Log::Abstraction->new(diag => 'none');

    # A hash reference works too; messages in German
    my $german = Test::Log::Abstraction->new({ country => 'DE' });

    # A clone that prints everything; $logger is not changed
    my $loud = $logger->new(diag => 'all');

=head3 API SPECIFICATION

=head4 Input

    {
        verbose => { type => 'scalar', optional => 1 },
        diag => { type => ['string', 'arrayref'], optional => 1 },
        level => { type => 'string', optional => 1 },
        lang => { type => 'string', optional => 1, matches => qr/\A(?:(?i:auto)|[A-Za-z]{2,3}(?:[_.\@-][\w.\@-]*+)?)\z/ },
        country => { type => 'string', optional => 1, matches => qr/\A[A-Za-z]{2}\z/ },
        i18n => { type => 'hashref', optional => 1 },
    }

Domains (valid / invalid / boundaries):

    verbose   valid: any plain value, Perl truth decides ('0', '' and undef
              are off; '00', '0.0' and ' ' are on); absent: from
              TEST_VERBOSE or VERBOSE.  Invalid: any reference.
    diag      valid: 'all' or 'none' (any case); a level name (any case),
              which prints severity 0 (emergency) up to that level's
              number, 7 (trace) being every level; an array reference of
              level names, [] printing nothing and duplicates counting
              once; absent or undef: $config{diag}.  Invalid: any other
              string, including '' and numbers such as '4'; a list
              element that is not a level name (or is 'all'); a hash,
              code or scalar reference.
    level     valid: the 16 level names, any case, setting 0 (emergency)
              to 7 (trace); absent or undef: $config{level}.  Invalid:
              '', numbers (even 0 to 7), any other name.
    lang      valid: 'auto' (any case); 2 or 3 ASCII letters, then
              optionally one of _ . @ - and anything else ('de',
              'eng', 'de_DE.UTF-8', 'zh-Hant').  A code with no catalogue
              ('ja', 'eng') gives 'en'.  Invalid: 1 letter, 4 or more
              letters, '', digits, a non-ASCII letter in the code, any
              whitespace or newline.
    country   valid: exactly 2 ASCII letters, any case; one with no
              mapping ('JP') gives 'en'.  Invalid: 1 or 3 letters, '',
              digits, non-ASCII letters.
    i18n      valid: a hash reference (even empty).  Invalid: any other
              type.

An "invalid argument" explanation, and a level or diag name repeated in an
error, is at most 200 characters; one longer is cut to 200 and ends with
"...".  Control characters in it are shown as C<\xNN>.

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

All of these stop the program (C<croak>).

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    invalid diag level 'X'          X is not a level name         Use a name from the level table
    diag must be a level name ...   diag is a hash or code ref    Give a string or an array ref
    invalid syslog level 'X'        the level option is unknown   Use a name from the level table
    invalid argument: ...           an option has the wrong type  Fix the option that is named
                                    or format

=head3 PSEUDOCODE

    if new() was called on a logger object:
        options = the object's options, replaced by the new options
        build a logger from the options, with a copy of the messages
        copy verbose and level from the object, unless new values were given
    else:
        if new() was called as a function, the first argument is an option
        turn the arguments into a hash (ignore an odd-length list)
        check the options
        choose the language, then the diag rule, then the level
    return the logger

=cut

=head2 trace, debug, info, notice, warn, error, fatal, critical, alert, emergency

Store a message at this level.

=head3 Purpose

These are the methods that the code under test calls to log something.
There is one method for each L<Log::Abstraction> level, and one for each
syslog name: C<warning>, C<err>, C<crit>, C<emerg>, C<panic> and
C<informational>.  Each method stores the message under the name that was
called, and may print it (see L</Which messages are printed>).

By default:

=over 4

=item * C<trace>, C<debug>, C<info>, C<informational>, C<notice> - stored,
not printed.

=item * C<warn>, C<warning>, C<error>, C<err>, C<critical>, C<crit>,
C<fatal>, C<alert>, C<emergency>, C<emerg>, C<panic> - stored and printed.

=back

=head3 Args

Any list of values.  They are turned into one message like this:

=over 4

=item * All the values are joined together, with nothing between them.

=item * One newline at the end is removed.

=item * If the only value is an array reference, its items are the parts
of the message.

=item * If there are two or more values and the last one is a hash
reference, that hash is not part of the message.  A copy of it is stored as
C<fields>.  An empty hash is dropped.

=item * A hash reference in the message is written as
C<{key =E<gt> value, ...}>, with the keys sorted.  An array reference is
written as C<[a, b]>.  So you can match their contents.

=item * C<undef> is written as the text C<undef>.  There is no warning.

=item * An object is written as Perl normally writes it.  If the object
has its own text form (overloaded C<"">), that form is used.

=item * A structure that contains itself is written as C<(cycle)> at the
point where it repeats.

=back

=head3 Returns

The logger, as in L<Log::Abstraction>.  So you can chain calls:
C<< $logger->info('a')->info('b') >>.

=head3 Side Effects

Adds one entry to the stored messages.  May print the message.  The
variables C<$@> and C<$!> are not changed.  So you can log inside an error
handler without losing the error.

=head3 EXAMPLE

    $logger->warn('something looks wrong');
    $logger->warn('file ', $name, ' is empty');          # joined: one message
    $logger->info('started', { pid => $$ });             # message + fields
    $logger->error({ error => 'cannot open file' });     # hash as the message
    $logger->debug(['part 1, ', 'part 2']);              # array of parts

=head3 API SPECIFICATION

=head4 Input

    {
        messages => { type => 'arrayref', position => 0, slurp => 1 },
    }

Domains: any number of arguments (0 gives an empty message) of any
kind and length.  Exactly one trailing newline is removed (so "m\n\n"
keeps one).  A trailing hash after one or more values is fields; an empty
one is dropped; a blessed hash is part of the message.  Text may be ASCII,
decoded text in any script (accents, CJK, emoji and emoji sequences,
combining marks, right-to-left text, zero-width characters) or bytes; it
is stored with its length unchanged.  See L</ENCODING> for how it is
printed.

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    X() must be called on an        not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head2 is_trace, is_debug, is_info, is_notice, is_warn, is_error, is_critical, is_alert, is_emergency

Ask if a level is turned on.

=head3 Purpose

Some code only builds a log message if the level is turned on, for
example C<< if($logger->is_debug()) { ... } >>.  These methods answer that
question, as L<Log::Abstraction> does.

=head3 Args

None.

=head3 Returns

1 if the level is turned on, otherwise 0.  A level is turned on when its
number is the same as, or lower than, the logger's level (see L</level>).
The default level is C<trace>, so all these methods return 1.

=head3 Side Effects

None.

=head3 EXAMPLE

    $logger->level('warning');
    $logger->is_warn();     # 1
    $logger->is_error();    # 1 (more serious than warning)
    $logger->is_info();     # 0 (less serious than warning)

=head3 API SPECIFICATION

=head4 Input

    {}

Domains: no arguments.  Each predicate is 1 exactly when its level's
number is at or below the logger's level: at level 0 (emergency) only
is_emergency is 1; at level 7 (trace) all are 1.

=head4 Output

    { type => 'boolean' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    is_X() must be called on an     not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head2 AUTOLOAD

Handle a call to a method that does not exist.

=head3 Purpose

Perl calls this when the code under test calls a method that this class
does not have - usually a misspelt level, such as C<wran>.  Any name
works, even an empty one (C<< $logger->$name() >> with C<$name = ''>).  Instead of
stopping the test, the message is stored under the name that was called,
and a notice is printed.  The notice is always printed, whatever the
C<diag> setting, so the mistake is not hidden.

=head3 Args

The same as a level method.

=head3 Returns

The logger.

=head3 Side Effects

Adds one entry, with the called name as its level.  Prints
C<no method 'name'>.

=head3 EXAMPLE

    $logger->wran('oops');    # stored at level 'wran'; a notice is printed
    is($logger->count('wran'), 1, 'the misspelt call was stored');

=head3 API SPECIFICATION

=head4 Input

    {
        messages => { type => 'arrayref', position => 0, slurp => 1 },
    }

Domains: any method name, including '', non-ASCII names and very long
names.  The message is stored under the name in lower case.

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    no method 'X'                   X is not a method or a level  Fix the method name
                                    (notice; the test goes on)
    X() must be called on an        an unknown method was called  Call it on a logger object
    object, not on the class        on the class name (croak)

=cut

=head2 messages

Get the stored messages.

=head3 Purpose

Let your test look at everything that was logged.

=head3 Args

None.

=head3 Returns

A reference to a new array.  It has one hash reference for each message,
oldest first.  Each hash has these keys:

=over 4

=item * C<level> - the level name, in lower case, as it was called.

=item * C<message> - the message text.

=item * C<fields> - only when fields were given: a hash reference.

=back

The array is a copy, as in L<Log::Abstraction>.  Adding or removing items
in it does not change the stored messages.  But the hashes in it are the
stored hashes (see L</COMMON PITFALLS>).

=head3 Side Effects

None.

=head3 EXAMPLE

    foreach my $entry (@{ $logger->messages() }) {
        diag("$entry->{level}: $entry->{message}");
    }

    my $first = $logger->messages()->[0];
    is($first->{level}, 'warn', 'the first message is a warning');

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    { type => 'arrayref' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    messages() must be called on    not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 clear

Delete all stored messages.

=head3 Purpose

Start again with an empty list, for example between two steps of a test.

=head3 Args

None.

=head3 Returns

The logger, so you can chain calls.

=head3 Side Effects

All stored messages are deleted.  The settings (C<verbose>, C<level>,
C<diag>, language) do not change.  On a logger with no messages, it does
nothing, so it is safe to call before every step.

=head3 EXAMPLE

    $logger->clear();
    $logger->clear()->empty('nothing logged yet');

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    clear() must be called on an    not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head2 count

Count the stored messages.

=head3 Purpose

Check how much was logged, in total or at one level.

=head3 Args

=over 4

=item * C<$level> - optional.  Count only messages at this level.  Upper or
lower case does not matter.  Different names for the same level are counted
apart: C<count('warn')> does not count C<warning()> calls.

=back

=head3 Returns

The number of messages: 0 or more.

=head3 Side Effects

None.

=head3 EXAMPLE

    is($logger->count(), 3, 'three messages in total');
    is($logger->count('error'), 1, 'one of them is an error');

=head3 API SPECIFICATION

=head4 Input

    {
        level => { type => 'string', optional => 1, position => 0 },
    }

Domains: undef counts every message; a string counts messages at that
level, any case ('', '0' and unknown names give 0; aliases are separate
names).  Invalid: any reference.

=head4 Output

    { type => 'integer', min => 0 }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    count() must be called on an    not called on a logger        Call it on a logger object
    object, not on the class        (croak)
    invalid argument: ...           the level is not a string     Give a level name
                                    (croak)

=cut

=head2 like

Test that a stored message matches a pattern.

=head3 Purpose

The test passes if at least one stored message matches the pattern.

=head3 Args

=over 4

=item * C<$pattern> - required.  A C<qr//> regular expression, or a string.
A string is also used as a regular expression.

=item * C<$name> - optional.  The name of the test.

=back

=head3 Returns

True if the test passed, false if it failed.

=head3 Side Effects

Adds one test result to the TAP output.  If the test fails, all stored
messages are printed under it (at most 20, then a count of the others).

=head3 EXAMPLE

    $logger->like(qr/updated/, 'the update was logged');
    $logger->like(qr/^Cannot open/i, 'the open error was logged');

=head3 API SPECIFICATION

=head4 Input

    {
        pattern => { type => ['regex', 'string'], position => 0 },
        name => { type => 'string', optional => 1, position => 1 },
    }

Domains: pattern - a qr// or a string, which is compiled as a regular
expression ('' matches every message).  Invalid: undef, any other
reference, a string that does not compile or can never match.  name -
undef, or any string (including '' and non-ASCII text).  Invalid: a
reference.

=head4 Output

    { type => 'boolean' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    like() needs a pattern          no pattern was given (croak)  Give a qr// or a string
    invalid argument: ...           the pattern is not a qr// or  Give a qr// or a string
                                    a string, does not compile,   that is a valid regex
                                    or can never match (croak)
    N messages were captured:       the test failed; the stored   Compare them with the pattern
                                    messages follow (output)
    like() must be called on        not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 unlike

Test that no stored message matches a pattern.

=head3 Purpose

The test passes if no stored message matches the pattern.  It also passes
when there are no messages.

=head3 Args

=over 4

=item * C<$pattern> - required.  A C<qr//> regular expression, or a string.
A string is also used as a regular expression.

=item * C<$name> - optional.  The name of the test.

=back

=head3 Returns

True if the test passed, false if it failed.

=head3 Side Effects

Adds one test result to the TAP output.  If the test fails, the messages
that matched are printed under it.

=head3 EXAMPLE

    $logger->unlike(qr/fatal/i, 'nothing fatal was logged');

=head3 API SPECIFICATION

=head4 Input

    {
        pattern => { type => ['regex', 'string'], position => 0 },
        name => { type => 'string', optional => 1, position => 1 },
    }

Domains: as for L</like>.  Note that '' matches every message, so
unlike('') fails whenever anything was logged.

=head4 Output

    { type => 'boolean' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    unlike() needs a pattern        no pattern was given (croak)  Give a qr// or a string
    invalid argument: ...           the pattern is not a qr// or  Give a qr// or a string
                                    a string, does not compile,   that is a valid regex
                                    or can never match (croak)
    N messages matched:             the test failed; the          Look at the listed messages
                                    matching messages follow
    unlike() must be called on      not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 has_level

Test that something was logged at a level.

=head3 Purpose

The test passes if at least one message was stored at this level.

=head3 Args

=over 4

=item * C<$level> - required.  The level name.  Upper or lower case does
not matter.  Different names for the same level are different:
C<has_level('warn')> does not see C<warning()> calls.

=item * C<$name> - optional.  The name of the test.

=back

=head3 Returns

True if the test passed, false if it failed.

=head3 Side Effects

Adds one test result to the TAP output.  If the test fails, all stored
messages are printed under it, so you can see which levels were used.

=head3 EXAMPLE

    $logger->has_level('error', 'the failure was logged');

=head3 API SPECIFICATION

=head4 Input

    {
        level => { type => 'string', position => 0 },
        name => { type => 'string', optional => 1, position => 1 },
    }

Domains: level - a string, any case ('' and unknown names match
nothing; aliases are separate names).  Invalid: undef, any reference.
name - as for L</like>.

=head4 Output

    { type => 'boolean' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    has_level() needs a level name  no level was given (croak)    Give a level name
    invalid argument: ...           the level is not a string     Give a level name
                                    (croak)
    N messages were captured:       the test failed; the stored   Look at the listed levels
                                    messages follow (output)
    has_level() must be called on   not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 empty

Test that nothing was logged.

=head3 Purpose

The test passes if there are no stored messages.  Use it to check that a
normal run logs nothing.

=head3 Args

=over 4

=item * C<$name> - optional.  The name of the test.

=back

=head3 Returns

True if the test passed, false if it failed.

=head3 Side Effects

Adds one test result to the TAP output.  If the test fails, the stored
messages are printed under it.

=head3 EXAMPLE

    $logger->empty('a normal run logs nothing');

=head3 API SPECIFICATION

=head4 Input

    {
        name => { type => 'string', optional => 1, position => 0 },
    }

Domains: name - undef, or any string.  Invalid: a reference.

=head4 Output

    { type => 'boolean' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    N messages were captured:       the test failed; the stored   Look at the listed messages
                                    messages follow (output)
    empty() must be called on       not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 verbose

Get or change verbose mode.

=head3 Purpose

In verbose mode, every message is printed, whatever the C<diag> rule says.
This helps when you are finding out why a test fails.

=head3 Args

=over 4

=item * C<$value> - optional.  True turns verbose mode on, false turns it
off.  Without an argument, nothing changes.

=back

=head3 Returns

The setting after the call: 1 (on) or 0 (off).

=head3 Side Effects

Changes the setting, when you give an argument.

=head3 EXAMPLE

    $logger->verbose(1);           # print everything from now on
    my $on = $logger->verbose();   # 1

=head3 API SPECIFICATION

=head4 Input

    {
        value => { type => 'scalar', optional => 1, position => 0 },
    }

Domains: absent - get only; otherwise Perl truth decides ('0', '' and
undef are off; '0.0' is on).

=head4 Output

    { type => 'integer', min => 0, max => 1 }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    verbose() must be called on an  not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head2 level

Get or change the logger's level.

=head3 Purpose

Code under test may read or change the level, as it can with
L<Log::Abstraction/level>.  The level only changes the answers of the
C<is_*> methods.  Every message is still stored.

=head3 Args

=over 4

=item * C<$name> - optional.  A level name.  Upper or lower case does not
matter.

=back

=head3 Returns

=over 4

=item * No argument: the level's number, from 0 to 7.

=item * A known level name: the logger, so you can chain calls.

=item * An unknown level name: C<undef>, as in L<Log::Abstraction>.

=back

=head3 Side Effects

With a known name, the level changes.  With an unknown name, nothing
changes and a warning is printed.

=head3 EXAMPLE

    $logger->level('error');
    print $logger->level(), "\n";    # 3

=head3 API SPECIFICATION

=head4 Input

    {
        name => { type => 'string', optional => 1, position => 0 },
    }

Domains: absent or undef - get only; one of the 16 level names, any
case - set (0 for emergency to 7 for trace).  Anything else - '', numbers
such as '0' or '8', unknown names - warns and returns undef.

=head4 Output

    { type => ['integer', 'object'], optional => 1 }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    invalid syslog level 'X'        X is not a level name         Use a name from the level table
                                    (warning; returns undef)
    level() must be called on       not called on a logger        Call it on a logger object
    an object, not on the class     (croak)

=cut

=head2 flush

Do nothing.

=head3 Purpose

In L<Log::Abstraction>, C<flush()> sends e-mail messages that are waiting.
The test logger never sends e-mail, but the code under test may still call
C<flush()>, so it exists.

=head3 Args

None.

=head3 Returns

The logger, so you can chain calls.

=head3 Side Effects

None.

=head3 EXAMPLE

    $logger->flush();

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    flush() must be called on an    not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head2 lang

Get the language of this module's messages.

=head3 Purpose

Let a test check which language was chosen from the C<lang> and C<country>
options or the environment.

=head3 Args

None.

=head3 Returns

A language code: C<en>, C<de>, C<fr>, C<zh>, or a code that you gave in the
C<i18n> option.

=head3 Side Effects

None.

=head3 EXAMPLE

    my $lang = Test::Log::Abstraction->new(country => 'FR')->lang();    # 'fr'

=head3 API SPECIFICATION

=head4 Input

    {}

=head4 Output

    { type => 'string', matches => qr/\A[a-z]{2,3}\z/ }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    lang() must be called on an     not called on a logger        Call it on a logger object
    object, not on the class        (croak)

=cut

=head1 PROTECTED METHODS

Only this class, and classes that inherit from it, may call these methods
(L<Sub::Protected> checks this).  A subclass may replace them.

=head2 _emit

Print one line of test output.

=head3 Purpose

Every line that this module prints goes through this method.  A subclass
can replace it to send the lines somewhere else.

=head3 Args

=over 4

=item * C<$text> - the line to print.

=back

=head3 Returns

The logger.

=head3 Side Effects

Prints the line as a TAP comment, with L<Test::Builder/diag>.  This works
even if the test did not load L<Test::More>.  A Perl character string is
encoded as UTF-8 first, unless the output already has an encoding layer
(see L</ENCODING>).

=head3 EXAMPLE

    package My::Logger;
    use parent -norequire, 'Test::Log::Abstraction';

    # Send the lines to STDERR instead of the TAP output
    sub _emit {
        my ($self, $text) = @_;
        print STDERR "$text\n";
        return $self;
    }

=head3 API SPECIFICATION

=head4 Input

    {
        text => { type => 'string', position => 0 },
    }

=head4 Output

    { type => 'object', isa => 'Test::Log::Abstraction' }

=head3 MESSAGES

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    _emit() is a protected method   called from outside the class Call it from a subclass only
    ... (croak)                     and its subclasses

=cut

=head2 i18n

Make one of this module's messages, in the logger's language.

=head3 Purpose

All the text that this module shows to people comes from here.  So the
text can be translated, or changed, without changing the code.

=head3 Args

=over 4

=item * C<$key> - the name of the message, such as C<needs_pattern>.

=item * C<\%args> - optional.  Values for the placeholders in the message.
C<class> is filled in for you (the logger's class).  C<count> chooses the
singular or plural form.  C<gender> chooses a gender form.

=back

=head3 How a message template works

A template is a string.  C<%{name}s> is replaced by the value called
C<name>.  After the name you can use any C<sprintf> format letter, for
example C<%{count}d> or C<%{ratio}.2f>.  C<%%> gives one C<%>.  A value
that is missing becomes the text C<undef>, with no warning.

A template can also be a hash.  The keys are gender names (such as
C<male>, C<female>) or plural forms (C<zero>, C<one>, C<two>, C<few>,
C<many>, C<other>).  The values are templates, so they can be hashes too.
C<other> is used when nothing else fits.  C<zero> is used for a count of
0, if it is there.

    {
        zero  => 'no messages',
        one   => '%{count}d message',
        other => '%{count}d messages',
    }

=head3 Where the template is found

The first one found is used:

=over 4

=item 1. Your C<i18n> option, in the logger's language.

=item 2. This module's messages, in the logger's language.

=item 3. Your C<i18n> option, in English.

=item 4. This module's messages, in English.

=back

If the key is not found anywhere, the key itself is returned.

=head3 Returns

The finished message, as a Perl character string.

=head3 Side Effects

None.

=head3 EXAMPLE

    # Inside a subclass
    my $text = $self->i18n('needs_pattern', { method => 'like' });
    # "Test::Log::Abstraction: like() needs a pattern"

    # Your own message, with gender and plural forms.  i18n() is
    # protected, so call it from a method of your subclass.
    my $logger = My::Logger->new(i18n => {
        en => {
            logged => {
                male => { one => 'He logged %{count}d line', other => 'He logged %{count}d lines' },
                other => 'They logged %{count}d lines',
            },
        },
    });
    # In a method of My::Logger:
    $self->i18n('logged', { gender => 'male', count => 2 });    # 'He logged 2 lines'

=head3 API SPECIFICATION

=head4 Input

    {
        key => { type => 'string', position => 0 },
        args => { type => 'hashref', optional => 1, position => 1 },
    }

Domains: key - any string; undef renders as '', a reference as its
string form, and an unknown key is returned as it is.  args - a hash
reference; anything else is ignored.  count - a number selects a plural
form (0 uses 'zero' when present); anything else uses 'other'.

=head4 Output

    { type => 'string' }

=head3 MESSAGES

It never fails for any key or arguments.  The only error is about who may
call it:

    Message                         Meaning                       What to do
    ------------------------------  ----------------------------  ------------------------------
    i18n() is a protected method    called from outside the class Call it from a subclass only
    ... (croak)                     and its subclasses

=head3 PSEUDOCODE

    language = the logger's language (for a class name: the configured one)
    template = the first one found in the four places listed above
    if no template was found, return the key
    while the template is a hash:
        choose by gender, else by plural form, else 'other'
    replace each %{name}format with sprintf(format, the value of name)
    return the text

=cut