tests/test-plugin-docs.sh

   1 #!/usr/bin/env bash
   2 # nbdkit
   3 # Copyright Red Hat
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions are
   7 # met:
   8 #
   9 # * Redistributions of source code must retain the above copyright
  10 # notice, this list of conditions and the following disclaimer.
  11 #
  12 # * Redistributions in binary form must reproduce the above copyright
  13 # notice, this list of conditions and the following disclaimer in the
  14 # documentation and/or other materials provided with the distribution.
  15 #
  16 # * Neither the name of Red Hat nor the names of its contributors may be
  17 # used to endorse or promote products derived from this software without
  18 # specific prior written permission.
  19 #
  20 # THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
  21 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22 # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  23 # PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
  24 # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  27 # USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28 # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 # OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 # SUCH DAMAGE.
  32
  33 # Test the nbdkit <plugin> --help output matches the associated POD
  34 # documentation.
  35
  36 source ./functions.sh
  37 set -e
  38
  39 # There's no point doing this test under valgrind.
  40 skip_if_valgrind
  41
  42 rm -f plugin-keys.txt pod-keys.txt
  43 cleanup_fn rm -f plugin-keys.txt pod-keys.txt
  44
  45 errors=0
  46
  47 run_test ()
  48 {
  49     plugin="$1"
  50
  51     pod=../plugins/$plugin/nbdkit-$plugin-plugin.pod
  52     test -f "$pod"
  53
  54     # Get the key=value lines from the help output.
  55     nbdkit $plugin --help |
  56         grep -Eo '^[-_A-Za-z0-9]+=|^\[[-_A-Za-z0-9]+=\]' |
  57         $SED -e 's/\[//' -e 's/\]//' > plugin-keys.txt
  58
  59     # Get the key=value lines from the POD documentation.
  60     cat "$pod" |
  61         grep -Eo '^=item B<[-_A-Za-z0-9]+=|^=item \[B<[-_A-Za-z0-9]+=' |
  62         $SED -e 's/=item //' -e 's/B<//' -e 's/\[//' > pod-keys.txt
  63
  64     # Check each plugin --help key is mentioned in the POD
  65     # documentation.
  66     for key in `cat plugin-keys.txt`; do
  67         if ! grep -sq "^$key" pod-keys.txt; then
  68             echo "error: $pod: documentation does not mention '$key...'" >&2
  69             ((errors++)) ||:
  70         fi
  71     done
  72
  73     # Check each POD documentation key is mentioned in plugin --help.
  74     for key in `cat pod-keys.txt`; do
  75         if ! grep -sq "^$key" plugin-keys.txt; then
  76             echo -n "error: nbdkit-$plugin-plugin: " >&2
  77             echo "--help output does not mention '$key...'" >&2
  78             ((errors++)) ||:
  79         fi
  80     done
  81 }
  82
  83 do_test ()
  84 {
  85     case "$1" in
  86         cc|eval|golang|lua|ocaml|perl|python|ruby|rust|sh|tcl)
  87             # Skip all language plugins as this test doesn't
  88             # make sense for these.
  89             ;;
  90         S3|example4)
  91             # The --help output is for the language plugin (like
  92             # perl or python) not the actual plugin.  This is
  93             # really a bug in how we do --help output, for now
  94             # ignore.
  95             ;;
  96         blkio)
  97             # The --help output describes the generic PROPERTY= which
  98             # breaks the test.  Ignore it.
  99             ;;
 100         example2|example3)
 101             # The example documentation doesn't list options.
 102             # Should it?  Possibly, but ignore for now.
 103             ;;
 104         nbd)
 105             # Because of macOS SIP misfeature the DYLD_* environment
 106             # variable added by libnbd/run is filtered out and the
 107             # test won't work.  Skip it entirely on Macs.
 108             if test "$(uname)" != "Darwin"; then run_test $1; fi
 109             ;;
 110         vddk)
 111             # This plugin has many parameters and the --help output
 112             # directs you to the manual.  Ignore it.
 113             ;;
 114         *)
 115             run_test $1
 116             ;;
 117     esac
 118 }
 119 foreach_plugin do_test
 120
 121 if [ "$errors" -ge 1 ]; then exit 1; fi