Skip to content

Latest commit

 

History

History
545 lines (439 loc) · 12.8 KB

test.md

File metadata and controls

545 lines (439 loc) · 12.8 KB

Bash-Funk "test" module

This module contains internal functions to test commandline parsing.

The following commands are available when this module is loaded:

  1. -test-all
  2. -test-all-test
  3. -test-fn-flags
  4. -test-fn-multi-value-options
  5. -test-fn-multi-value-parameter-zero-or-more
  6. -test-fn-multi-value-parameters
  7. -test-fn-multi-value-parameters-variable-length
  8. -test-fn-noargs
  9. -test-fn-requires-existing
  10. -test-fn-requires-nonexistent
  11. -test-fn-single-value-options
  12. -test-fn-single-value-parameters
  13. -test-fn-single-value-parameters-first-optional

License

SPDX-FileCopyrightText: © Vegard IT GmbH (https://vegardit.com)
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-test-all

Usage: -test-all [OPTION]...

Executes the selftests of all loaded bash-funk commands.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Implementation:

for testfunc in $(compgen -A function -- -test-all-); do
   $testfunc || return 1
done

-test-all-test

Usage: -test-all-test [OPTION]...

Performs a selftest of all functions of this module by executing each function with option '--selftest'.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Implementation:

-test-all --selftest && echo || return 1
-test-fn-flags --selftest && echo || return 1
-test-fn-multi-value-options --selftest && echo || return 1
-test-fn-multi-value-parameter-zero-or-more --selftest && echo || return 1
-test-fn-multi-value-parameters --selftest && echo || return 1
-test-fn-multi-value-parameters-variable-length --selftest && echo || return 1
-test-fn-noargs --selftest && echo || return 1
-test-fn-requires-existing --selftest && echo || return 1
-test-fn-requires-nonexistent --selftest && echo || return 1
-test-fn-single-value-options --selftest && echo || return 1
-test-fn-single-value-parameters --selftest && echo || return 1
-test-fn-single-value-parameters-first-optional --selftest && echo || return 1

-test-fn-flags

Usage: -test-fn-flags [OPTION]...

Test function with custom flags.

Options:
-m, --myflag
        My flag.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-flags 
myflag was not specified
$ -test-fn-flags --myflag
myflag was specified
$ -test-fn-flags -m
myflag was specified

Implementation:

[[ $_myflag ]] && echo "myflag was specified" || echo "myflag was not specified"

-test-fn-multi-value-options

Usage: -test-fn-multi-value-options [OPTION]...

Test function with multi value options.

Options:
-a, --aa [...]
        Option a.
-b, --bb v1[,v2..2]
        Option b.
-c, --cc [...] (integer: ?-?)
        Option c.
-d, --dd [...] (integer: 1-5)
        Option d.
-e, --ee [...] (one of: [A,B,C])
        Option e.
-f, --ff [...] (pattern: "[a-z]+")
        Option f.
-g, --gg [...] (pattern: "[a-z]+")
        Option g.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-multi-value-options 
aa: bb: cc: dd: ee: ff: gg:
$ -test-fn-multi-value-options --aa
aa: bb: cc: dd: ee: ff: gg:
$ -test-fn-multi-value-options --aa foo
aa:foo bb: cc: dd: ee: ff: gg:
$ -test-fn-multi-value-options --aa foo,bar
aa:foo bar bb: cc: dd: ee: ff: gg:
$ -test-fn-multi-value-options --bb foo,bar
aa: bb:foo bar cc: dd: ee: ff: gg:
$ -test-fn-multi-value-options --cc 123,45
aa: bb: cc:123 45 dd: ee: ff: gg:
$ -test-fn-multi-value-options --dd 1,3
aa: bb: cc: dd:1 3 ee: ff: gg:
$ -test-fn-multi-value-options --ee A,B
aa: bb: cc: dd: ee:A B ff: gg:
$ -test-fn-multi-value-options --ff foo,bar
aa: bb: cc: dd: ee: ff:foo bar gg:

Implementation:

echo "aa:${_aa[@]} bb:${_bb[@]} cc:${_cc[@]} dd:${_dd[@]} ee:${_ee[@]} ff:${_ff[@]} gg:${_gg[@]}"

-test-fn-multi-value-parameter-zero-or-more

Usage: -test-fn-multi-value-parameter-zero-or-more [OPTION]... [AA]...

Test function with multi value parameters.

Parameters:
  AA (integer: ?-?)
      Param AA.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-multi-value-parameter-zero-or-more 
AA:
$ -test-fn-multi-value-parameter-zero-or-more 12
AA:12
$ -test-fn-multi-value-parameter-zero-or-more 12 34
AA:12 34

Implementation:

echo "AA:${_AA[@]}"

-test-fn-multi-value-parameters

Usage: -test-fn-multi-value-parameters [OPTION]... AA1 AA2 BB1 BB2 CC1 CC2 DD1 DD2 EE1 EE2 [FF]...

Test function with multi value parameters.

Parameters:
  AA (2 required)
      Param AA.
  BB (2 required, integer: ?-?)
      Param BB.
  CC (2 required, integer: 1-5)
      Param CC.
  DD (2 required, one of: [A,B,C])
      Param DD.
  EE (2 required, pattern: "[a-z]+")
      Param EE.
  FF (pattern: "[a-z]+")
      Param FF.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-multi-value-parameters aa aa 12 34 1 5 A B foo bar
AA:aa aa BB:12 34 CC:1 5 DD:A B EE:foo bar FF:
$ -test-fn-multi-value-parameters aa aa 12 34 1 5 A B foo bar a b c d e f
AA:aa aa BB:12 34 CC:1 5 DD:A B EE:foo bar FF:a b c d e f

Implementation:

echo "AA:${_AA[@]} BB:${_BB[@]} CC:${_CC[@]} DD:${_DD[@]} EE:${_EE[@]} FF:${_FF[@]}"

-test-fn-multi-value-parameters-variable-length

Usage: -test-fn-multi-value-parameters-variable-length [OPTION]... [AA1..2] BB1 BB2

Test function with multi value parameters.

Parameters:
  AA (0 to 2 required, integer: ?-?)
      Param AA.
  BB (2 required, integer: ?-?)
      Param BB.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-multi-value-parameters-variable-length 12 34
AA: BB:12 34

Implementation:

echo "AA:${_AA[@]} BB:${_BB[@]}"

-test-fn-noargs

Usage: -test-fn-noargs [OPTION]...

Test function with no arguments.

Options:
-v, --verbose
        Prints additional information during command execution.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-noargs 

$ -test-fn-noargs --verbose
verbose mode

Implementation:

[[ $_verbose ]] && echo "verbose mode" || :

-test-fn-requires-existing

Usage: -test-fn-requires-existing [OPTION]...

Test function that requires presence of an existing command - thus always succeeds.

Requirements:
  + Command 'hash' must be available.

Options:
-v, --verbose
        Prints additional information during command execution.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-requires-existing

Implementation:

[[ $_verbose ]] && echo "verbose mode" || :

-test-fn-requires-nonexistent

Usage: -test-fn-requires-nonexistent [OPTION]...

Test function that requires presence of a nonexistent command - thus always fails.

Requirements:
  + Command 'some_random_nonexistent_command' must be available.

Options:
-v, --verbose
        Prints additional information during command execution.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Implementation:

[[ $_verbose ]] && echo "verbose mode" || :

-test-fn-single-value-options

Usage: -test-fn-single-value-options [OPTION]...

Test function with single value options.

Options:
-a, --aa [v] (default: 'cat')
        Option a.
-b, --bb v
        Option b.
-c, --cc v (integer: ?-?)
        Option c.
-d, --dd v (integer: 1-5)
        Option d.
-e, --ee v (one of: [A,B,C])
        Option e.
-f, --ff v (pattern: "[a-z]+")
        Option f.
-g, --gg v (pattern: "[a-z]+")
        Option g.
    -----------------------------
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-single-value-options 
aa: bb: cc: dd: ee: ff: gg:
$ -test-fn-single-value-options --aa
aa:cat bb: cc: dd: ee: ff: gg:
$ -test-fn-single-value-options --aa foo
aa:foo bb: cc: dd: ee: ff: gg:
$ -test-fn-single-value-options --bb foo
aa: bb:foo cc: dd: ee: ff: gg:
$ -test-fn-single-value-options --cc 12345
aa: bb: cc:12345 dd: ee: ff: gg:
$ -test-fn-single-value-options --dd 3
aa: bb: cc: dd:3 ee: ff: gg:
$ -test-fn-single-value-options --ee A
aa: bb: cc: dd: ee:A ff: gg:
$ -test-fn-single-value-options --ff foo
aa: bb: cc: dd: ee: ff:foo gg:
$ -test-fn-single-value-options -ab foo
aa:cat bb:foo cc: dd: ee: ff: gg:

Implementation:

echo "aa:$_aa bb:$_bb cc:$_cc dd:$_dd ee:$_ee ff:$_ff gg:$_gg"

-test-fn-single-value-parameters

Usage: -test-fn-single-value-parameters [OPTION]... AA BB CC DD EE [FF]

Test function with single value parameters.

Parameters:
  AA (required)
      Param AA.
  BB (required, integer: ?-?)
      Param BB.
  CC (required, integer: 1-5)
      Param CC.
  DD (required, one of: [A,B,C])
      Param DD.
  EE (required, pattern: "[a-z]+")
      Param EE.
  FF (default: 'cat', pattern: "[a-z]+")
      Param FF.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-single-value-parameters aa 12 5 A foo
AA:aa BB:12 CC:5 DD:A EE:foo FF:cat
$ -test-fn-single-value-parameters aa 12 5 A foo bar
AA:aa BB:12 CC:5 DD:A EE:foo FF:bar

Implementation:

echo "AA:$_AA BB:$_BB CC:$_CC DD:$_DD EE:$_EE FF:$_FF"

-test-fn-single-value-parameters-first-optional

Usage: -test-fn-single-value-parameters-first-optional [OPTION]... [AA] BB

Test function with single value parameters where the first one is optional.

Parameters:
  AA (integer: ?-?)
      Param AA.
  BB (required, integer: ?-?)
      Param BB.

Options:
    --help
        Prints this help.
    --tracecmd
        Enables bash debug mode (set -x).
    --selftest
        Performs a self-test.
    --
        Terminates the option list.

Examples:
$ -test-fn-single-value-parameters-first-optional 22
AA: BB:22
$ -test-fn-single-value-parameters-first-optional 11 22
AA:11 BB:22

Implementation:

echo "AA:$_AA BB:$_BB"