Fix command plumbing for spin and spin-file

Plumb spin and spin-file through App::DocKnot::Command to the
docknot frontend again.  Add documentation for those commands and
their options.  Add a test for the command-line interface to
ensure that plumbing keeps working in the future.

Move the logic to compare a tree of spun files into the
Test::DocKnot::Spin module so that it can be shared between the
command-line test and the API test.

Add the test library modules to POD syntax and spelling checks.

1 files changed, 86 insertions, 3 deletions

diff --git a/t/lib/Test/DocKnot/Spin.pm b/t/lib/Test/DocKnot/Spin.pm
index 95ee285..0a20ea5 100644
--- a/t/lib/Test/DocKnot/Spin.pm
+++ b/t/lib/Test/DocKnot/Spin.pm
@@ -12,11 +12,16 @@ use 5.024;
 use autodie;
 use warnings;
 
+use Cwd qw(getcwd);
 use Exporter qw(import);
+use File::Compare qw(compare);
+use File::Find qw(find);
 use Perl6::Slurp qw(slurp);
 use Test::RRA qw(is_file_contents);
 
-our @EXPORT_OK = qw(is_spin_output);
+use Test::More;
+
+our @EXPORT_OK = qw(is_spin_output is_spin_output_tree);
 
 ##############################################################################
 # Test functions
@@ -50,6 +55,73 @@ sub is_spin_output {
     return;
 }
 
+# Compare a spin output tree with an expected output tree, with the same
+# modification logic as is_spin_output.
+#
+# $output   - The output tree
+# $expected - The expected output tree
+# $message  - The descriptive message for the test
+#
+# Returns: The number of tests run.
+sub is_spin_output_tree {
+    my ($output, $expected, $message) = @_;
+    my $cwd = getcwd();
+    my %seen;
+    my @missing;
+
+    # Function that compares each of the output files in the tree, called from
+    # File::Find on the output directory.
+    my $check_output = sub {
+        my $file = $_;
+        return if -d $file;
+
+        # Determine the relative path and mark it as seen.
+        my $path = File::Spec->abs2rel($File::Find::name, $output);
+        $seen{$path} = 1;
+
+        # Find the corresponding expected file.
+        my $expected_file
+          = File::Spec->rel2abs(File::Spec->catfile($expected, $path), $cwd);
+
+        # Compare HTML output using is_spin_output and all other files as
+        # copies.
+        if ($file =~ m{ [.] html \z }xms) {
+            is_spin_output($file, $expected_file, "$message ($path)");
+        } else {
+            is(compare($file, $expected_file), 0, "$message ($path)");
+        }
+        return;
+    };
+
+    # Function that checks that every file in the expected output tree was
+    # seen in the generated output tree, called from File::Find on the
+    # expected directory.
+    my $check_files = sub {
+        my $file = $_;
+        return if -d $file;
+
+        # Determine the relative path and make sure it was in the %seen hash.
+        my $path = File::Spec->abs2rel($File::Find::name, $expected);
+        if ($seen{$path}) {
+            delete $seen{$path};
+        } else {
+            push(@missing, $path);
+        }
+        return;
+    };
+
+    # Compare the output.
+    find($check_output, $output);
+    my $count = keys(%seen);
+
+    # Check that there aren't any missing files.
+    find($check_files, $expected);
+    is_deeply(\@missing, [], 'All expected files generated');
+
+    # Return the count of tests.
+    return $count + 1;
+}
+
 ##############################################################################
 # Module return value and documentation
 ##############################################################################
@@ -58,7 +130,7 @@ sub is_spin_output {
 __END__
 
 =for stopwords
-Allbery Allbery sublicense MERCHANTABILITY NONINFRINGEMENT
+Allbery Allbery sublicense MERCHANTABILITY NONINFRINGEMENT DocKnot
 
 =head1 NAME
 
@@ -68,9 +140,12 @@ Test::DocKnot::Spin - Helper functions for testing spin
 
     use Test::DocKnot::Spin qw(is_spin_output);
 
-    $spin->spin_command($input, $output);
+    $spin->spin_file($input, $output);
     is_spin_output($output, $expected, 'Check a single file');
 
+    $spin->spin_tree($input_path, $output_path);
+    is_spin_output_tree($output_path, $expected_path, 'Check a tree');
+
 =head1 DESCRIPTION
 
 This module collects utility functions that are useful for testing the
@@ -93,6 +168,14 @@ App::DocKnot::Spin, compare it to the expected output in the file named
 EXPECTED.  MESSAGE is the message to print with the test results for easy
 identification.
 
+=item is_spin_output_tree(OUTPUT, EXPECTED, MESSAGE)
+
+Compare the output tree at OUTPUT with the expected output tree at EXPECTED,
+using the same comparison algorithm as is_spin_output().  MESSAGE with the
+message to print with the test results for easy identification.
+
+=back
+
 =head1 AUTHOR
 
 Russ Allbery <rra@cpan.org>