=head1 NAME

Deprecated Syntax

=head1 SYNOPSIS

This document tries summarized common mistakes in the test suite. If you
help refactoring the suite, or write new tests, read this document first.

=head1 DEPRECATED SYNTAX

=head2 Old POD

Old POD looks like this:

    =head1 heading
    ...
    =cut

The new POD looks like this:

    =begin stuff
    ...
    =end stuff

All new files, and all below C<t/spec/> should follow the new conventions.

=head2 Array indexes with negative numbers

The Perl 5 style negative array indexes C<@array[-1]> are spelled
C<@array[*-1]> in Perl 6.

=head2 pos()

C<pos> is dead. C<$/.to> is the replacement.

=head2 length()

C<length> is gone. Hashes should use C<keys>, C<values>, or the hash in numeric
context. For arrays, you want C<elems> or the array in numeric context. For
strings, you want one of C<chars>, C<graphs>, C<codes>, or C<bytes>.

=head2 undef is dead

There is no C<undef> term anymore. For a scalar undef, use C<Any>, or C<Mu>
if you know what you're doing and you think it's right. For an undefined value
of a certain type just use its type object, so an undefined integer would just
be C<Int>.

To test that something is not defined, use one of the alternations below,
where the first three are preferred (because they use less advanced features):

    ok !defined($something), 'description';
    ok !$something.defined,  'description';
    ok $somethiing.notdef,   'description';
    ok $something ~~ *.notdef,  'description';

=head2 Special Pugs variables

Some tests rely on C<$?PUGS_BACKEND> and similar variables. Since they are not
specced, they cause failures on other implementations. Either remove these
variables altogether, or fudge them by prepending C<#?pugs emit> on every
such line.

=head2 eval_dies_ok for tests that can fail at compile time

C<dies_ok> should only be used for tests that have to fail at run time. For
example non-existent subs are no such case. Always bare in mind that a clever
compiler might do some type inference and prove that there always will be an
error, and throw it at compile time.

If in doubt, use C<eval_dies_ok> instead. If you have a case where C<dies_ok>
is fine, remember to pass a code ref to it.

=head2 .perl isn't canonical

The C<perl> method (which does roughly the same as perl 5's Data::Dumper)
returns a string that, when evaluated, returns the same value as the original
one (but put in item context).

However it's result isn't guaranteed to be of any canonical form, for example
C<Str.perl> might return any legal quoting syntax. Testing for the exact value
of C<$anything.perl> is most likely an error

=head2 Type constraints on containers

Use type constraints only where they are needed to test what you want to test.
Especially be aware that C<my Int @a> declares an Array of Int values, and by
the same token C<my Array @a> actually declares an Array of Arrays. Most of
the time that's not what you want. The same goes for variables with the C<%>
and C<&> sigil: an additional type constraint acts on the values (or the
return value in case of C<&>).

=head2 Junction.values is deprecated

Calling C<.values> on a junction ordinarily autothreads, calling C<.values> on
each eigenstate.

=head2 A note on :todo<bug> and similar

Some tests (mostly outside of t/spec) look like this:

    is(foo(), bar(), 'testing whatever', :todo<bug>);

This form is a todo note for Pugs. Since this test suite is used by multiple
implementations, this should be replaced with a fudge command:

    #?pugs todo 'bug'
    is(foo(), bar(), 'testing whatever');

=cut

# vim: spell spelllang=en_us