is_deeply documentation misleading

[kentfredric]

The is_deeply documentation doesn't explain why:

my $path = path('.');
my $hash = {};
is_deeply( $path, "$path" ); # ok
is_deeply( $hash, "$hash" ); # fail

The documentation at present implies that if either of them is a non-ref, that both will be treated as non-refs.

"Similar to is(), except that if $got and $expected are references, it does a deep comparison walking each data structure to see if they are equivalent."

Which is what appears to happen for objects.

But pure refs are treated as a failure if their type is different,

The real mechanic behind why the first example passes and the second fails, is that Test::Builder::_unoverload is applied to all arguments in blanket fashion

Which means that if any arguments have string overloading support, they will be replaced with their string forms.

Which ultimately means if you have a system that looks slightly like this, then is_deeply is the wrong tool:

use Test::More;
use Path::Tiny;

{
  package Annoying;
  use overload q[""] => \&stringify;

  sub new {
    return bless [ int(rand 255) ], $_[0];
  }
  sub stringify {
    return "Annoying";
  }
  sub value {
    return $_[0]->[0];
  }
}

for ( 0 .. 20 ) {
  my ( $x , $y ) = ( Annoying->new(), Annoying->new() );
  is_deeply( $x, $y , sprintf "Annoying[%3s] == Annoying[%3s]", $x->value, $y->value );
}

done_testing;

ok 1 - Annoying[ 30] == Annoying[112]
ok 2 - Annoying[161] == Annoying[ 54]
ok 3 - Annoying[180] == Annoying[105]
ok 4 - Annoying[ 55] == Annoying[158]
ok 5 - Annoying[ 87] == Annoying[  5]
ok 6 - Annoying[139] == Annoying[226]
ok 7 - Annoying[234] == Annoying[220]
ok 8 - Annoying[190] == Annoying[101]
ok 9 - Annoying[ 72] == Annoying[195]
ok 10 - Annoying[204] == Annoying[ 46]
ok 11 - Annoying[212] == Annoying[105]
ok 12 - Annoying[225] == Annoying[  6]
ok 13 - Annoying[ 68] == Annoying[ 76]
ok 14 - Annoying[ 61] == Annoying[ 25]
ok 15 - Annoying[168] == Annoying[223]
ok 16 - Annoying[ 63] == Annoying[126]
ok 17 - Annoying[ 12] == Annoying[120]
ok 18 - Annoying[180] == Annoying[135]
ok 19 - Annoying[ 37] == Annoying[  0]
ok 20 - Annoying[218] == Annoying[ 60]
ok 21 - Annoying[155] == Annoying[186]
1..21