testing: be more explicit about contexts; example for is_deeply

Author: moritz

lib/Language/testing.pod

@@ -152,8 +152,8 @@ summary will not count skipped tests).
 =item ok($condition, $description?), nok($condition, $description?)
 
 The C<ok> function marks a test as passed if the given C<$condition>
-evaluates to C<True>.  The C<nok> function marks a test as passed if the
-given condition evaluates to C<False>.
+evaluates to C<True> in a boolean context. The C<nok> function marks
+a test as passed if the given condition evaluates to C<False>.
 
     plan 2;
 
@@ -166,7 +166,8 @@ given condition evaluates to C<False>.
 =item is($obtained, $expected, $description?)
 
 Marks a test as passed if the C<$obtained> and C<$expected> values are equal
-(i.e., they compare as equal when using the C<'eq'> operator).  The function
+when coerced to strings (i.e., they compare as equal when using the
+L<eq operator|/routine/eq>).  The function
 accepts an optional C<$description> of the test.
 
     my $pi = 3;
@@ -197,7 +198,27 @@ Marks a test as passed if the C<$obtained> and C<$expected> values are
 C<eqv>.  This is the best way to check for equality of (deep) data
 structures.  The function accepts an optional C<$description> of the test.
 
-TODO: add an example
+=begin code
+use v6;
+use Test;
+plan 1;
+
+sub count-chars(Str() $x) {
+    my %chars;
+    %chars{$_}++ for $x.comb;
+    return %chars;
+}
+my %expected =
+    f   => 1,
+    l   => 1,
+    e   => 3,
+    c   => 1,
+    ;
+is_deeply count-chars('fleece'), %expected, 'count-chars works on "fleece"';
+=end code
+
+Note that string comparison here would have been fragile, because hashes are
+not sorted, and converting a L<Hash|/type/Hash> to a string loses information.
 
 =head2 Numeric comparison within a tolerance of 1e-5