name : test_shellcomp.py # Copyright (c) Twisted Matrix Laboratories. # See LICENSE for details. """ Test cases for twisted.python._shellcomp """ import sys from io import BytesIO from typing import List, Optional from twisted.python import _shellcomp, reflect, usage from twisted.python.usage import CompleteFiles, CompleteList, Completer, Completions from twisted.trial import unittest class ZshScriptTestMeta(type): """ Metaclass of ZshScriptTestMixin. """ def __new__(cls, name, bases, attrs): def makeTest(cmdName, optionsFQPN): def runTest(self): return test_genZshFunction(self, cmdName, optionsFQPN) return runTest # add test_ methods to the class for each script # we are testing. if "generateFor" in attrs: for cmdName, optionsFQPN in attrs["generateFor"]: test = makeTest(cmdName, optionsFQPN) attrs["test_genZshFunction_" + cmdName] = test return type.__new__(cls, name, bases, attrs) class ZshScriptTestMixin(metaclass=ZshScriptTestMeta): """ Integration test helper to show that C{usage.Options} classes can have zsh completion functions generated for them without raising errors. In your subclasses set a class variable like so:: # | cmd name | Fully Qualified Python Name of Options class | # generateFor = [('conch', 'twisted.conch.scripts.conch.ClientOptions'), ('twistd', 'twisted.scripts.twistd.ServerOptions'), ] Each package that contains Twisted scripts should contain one TestCase subclass which also inherits from this mixin, and contains a C{generateFor} list appropriate for the scripts in that package. """ def test_genZshFunction(self, cmdName, optionsFQPN): """ Generate completion functions for given twisted command - no errors should be raised @type cmdName: C{str} @param cmdName: The name of the command-line utility e.g. 'twistd' @type optionsFQPN: C{str} @param optionsFQPN: The Fully Qualified Python Name of the C{Options} class to be tested. """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) # some scripts won't import or instantiate because of missing # dependencies (pyOpenSSL, etc) so we have to skip them. try: o = reflect.namedAny(optionsFQPN)() except Exception as e: raise unittest.SkipTest( "Couldn't import or instantiate " "Options class: %s" % (e,) ) try: o.parseOptions(["", "--_shell-completion", "zsh:2"]) except ImportError as e: # this can happen for commands which don't have all # the necessary dependencies installed. skip test. # skip raise unittest.SkipTest("ImportError calling parseOptions(): %s", (e,)) except SystemExit: pass # expected else: self.fail("SystemExit not raised") outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) outputFile.seek(0) outputFile.truncate() # now, if it has sub commands, we have to test those too if hasattr(o, "subCommands"): for cmd, short, parser, doc in o.subCommands: try: o.parseOptions([cmd, "", "--_shell-completion", "zsh:3"]) except ImportError as e: # this can happen for commands which don't have all # the necessary dependencies installed. skip test. raise unittest.SkipTest( "ImportError calling parseOptions() " "on subcommand: %s", (e,) ) except SystemExit: pass # expected else: self.fail("SystemExit not raised") outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) outputFile.seek(0) outputFile.truncate() # flushed because we don't want DeprecationWarnings to be printed when # running these test cases. self.flushWarnings() class ZshTests(unittest.TestCase): """ Tests for zsh completion code """ def test_accumulateMetadata(self): """ Are `compData' attributes you can place on Options classes picked up correctly? """ opts = FighterAceExtendedOptions() ag = _shellcomp.ZshArgumentsGenerator(opts, "ace", BytesIO()) descriptions = FighterAceOptions.compData.descriptions.copy() descriptions.update(FighterAceExtendedOptions.compData.descriptions) self.assertEqual(ag.descriptions, descriptions) self.assertEqual(ag.multiUse, set(FighterAceOptions.compData.multiUse)) self.assertEqual( ag.mutuallyExclusive, FighterAceOptions.compData.mutuallyExclusive ) optActions = FighterAceOptions.compData.optActions.copy() optActions.update(FighterAceExtendedOptions.compData.optActions) self.assertEqual(ag.optActions, optActions) self.assertEqual(ag.extraActions, FighterAceOptions.compData.extraActions) def test_mutuallyExclusiveCornerCase(self): """ Exercise a corner-case of ZshArgumentsGenerator.makeExcludesDict() where the long option name already exists in the `excludes` dict being built. """ class OddFighterAceOptions(FighterAceExtendedOptions): # since "fokker", etc, are already defined as mutually- # exclusive on the super-class, defining them again here forces # the corner-case to be exercised. optFlags = [ ["anatra", None, "Select the Anatra DS as your dogfighter aircraft"] ] compData = Completions( mutuallyExclusive=[["anatra", "fokker", "albatros", "spad", "bristol"]] ) opts = OddFighterAceOptions() ag = _shellcomp.ZshArgumentsGenerator(opts, "ace", BytesIO()) expected = { "albatros": {"anatra", "b", "bristol", "f", "fokker", "s", "spad"}, "anatra": {"a", "albatros", "b", "bristol", "f", "fokker", "s", "spad"}, "bristol": {"a", "albatros", "anatra", "f", "fokker", "s", "spad"}, "fokker": {"a", "albatros", "anatra", "b", "bristol", "s", "spad"}, "spad": {"a", "albatros", "anatra", "b", "bristol", "f", "fokker"}, } self.assertEqual(ag.excludes, expected) def test_accumulateAdditionalOptions(self): """ We pick up options that are only defined by having an appropriately named method on your Options class, e.g. def opt_foo(self, foo) """ opts = FighterAceExtendedOptions() ag = _shellcomp.ZshArgumentsGenerator(opts, "ace", BytesIO()) self.assertIn("nocrash", ag.flagNameToDefinition) self.assertIn("nocrash", ag.allOptionsNameToDefinition) self.assertIn("difficulty", ag.paramNameToDefinition) self.assertIn("difficulty", ag.allOptionsNameToDefinition) def test_verifyZshNames(self): """ Using a parameter/flag name that doesn't exist will raise an error """ class TmpOptions(FighterAceExtendedOptions): # Note typo of detail compData = Completions(optActions={"detaill": None}) self.assertRaises( ValueError, _shellcomp.ZshArgumentsGenerator, TmpOptions(), "ace", BytesIO() ) class TmpOptions2(FighterAceExtendedOptions): # Note that 'foo' and 'bar' are not real option # names defined in this class compData = Completions(mutuallyExclusive=[("foo", "bar")]) self.assertRaises( ValueError, _shellcomp.ZshArgumentsGenerator, TmpOptions2(), "ace", BytesIO(), ) def test_zshCode(self): """ Generate a completion function, and test the textual output against a known correct output """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) self.patch(sys, "argv", ["silly", "", "--_shell-completion", "zsh:2"]) opts = SimpleProgOptions() self.assertRaises(SystemExit, opts.parseOptions) self.assertEqual(testOutput1, outputFile.getvalue()) def test_zshCodeWithSubs(self): """ Generate a completion function with subcommands, and test the textual output against a known correct output """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) self.patch(sys, "argv", ["silly2", "", "--_shell-completion", "zsh:2"]) opts = SimpleProgWithSubcommands() self.assertRaises(SystemExit, opts.parseOptions) self.assertEqual(testOutput2, outputFile.getvalue()) def test_incompleteCommandLine(self): """ Completion still happens even if a command-line is given that would normally throw UsageError. """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) opts = FighterAceOptions() self.assertRaises( SystemExit, opts.parseOptions, [ "--fokker", "server", "--unknown-option", "--unknown-option2", "--_shell-completion", "zsh:5", ], ) outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) def test_incompleteCommandLine_case2(self): """ Completion still happens even if a command-line is given that would normally throw UsageError. The existence of --unknown-option prior to the subcommand will break subcommand detection... but we complete anyway """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) opts = FighterAceOptions() self.assertRaises( SystemExit, opts.parseOptions, [ "--fokker", "--unknown-option", "server", "--list-server", "--_shell-completion", "zsh:5", ], ) outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) outputFile.seek(0) outputFile.truncate() def test_incompleteCommandLine_case3(self): """ Completion still happens even if a command-line is given that would normally throw UsageError. Break subcommand detection in a different way by providing an invalid subcommand name. """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) opts = FighterAceOptions() self.assertRaises( SystemExit, opts.parseOptions, [ "--fokker", "unknown-subcommand", "--list-server", "--_shell-completion", "zsh:4", ], ) outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) def test_skipSubcommandList(self): """ Ensure the optimization which skips building the subcommand list under certain conditions isn't broken. """ outputFile = BytesIO() self.patch(usage.Options, "_shellCompFile", outputFile) opts = FighterAceOptions() self.assertRaises( SystemExit, opts.parseOptions, ["--alba", "--_shell-completion", "zsh:2"] ) outputFile.seek(0) # test that we got some output self.assertEqual(1, len(outputFile.read(1))) def test_poorlyDescribedOptMethod(self): """ Test corner case fetching an option description from a method docstring """ opts = FighterAceOptions() argGen = _shellcomp.ZshArgumentsGenerator(opts, "ace", None) descr = argGen.getDescription("silly") # docstring for opt_silly is useless so it should just use the # option name as the description self.assertEqual(descr, "silly") def test_brokenActions(self): """ A C{Completer} with repeat=True may only be used as the last item in the extraActions list. """ class BrokenActions(usage.Options): compData = usage.Completions( extraActions=[usage.Completer(repeat=True), usage.Completer()] ) outputFile = BytesIO() opts = BrokenActions() self.patch(opts, "_shellCompFile", outputFile) self.assertRaises( ValueError, opts.parseOptions, ["", "--_shell-completion", "zsh:2"] ) def test_optMethodsDontOverride(self): """ opt_* methods on Options classes should not override the data provided in optFlags or optParameters. """ class Options(usage.Options): optFlags = [["flag", "f", "A flag"]] optParameters = [["param", "p", None, "A param"]] def opt_flag(self): """junk description""" def opt_param(self, param): """junk description""" opts = Options() argGen = _shellcomp.ZshArgumentsGenerator(opts, "ace", None) self.assertEqual(argGen.getDescription("flag"), "A flag") self.assertEqual(argGen.getDescription("param"), "A param") class EscapeTests(unittest.TestCase): def test_escape(self): """ Verify _shellcomp.escape() function """ esc = _shellcomp.escape test = "$" self.assertEqual(esc(test), "'$'") test = "A--'$\"\\`--B" self.assertEqual(esc(test), '"A--\'\\$\\"\\\\\\`--B"') class CompleterNotImplementedTests(unittest.TestCase): """ Test that using an unknown shell constant with SubcommandAction raises NotImplementedError The other Completer() subclasses are tested in test_usage.py """ def test_unknownShell(self): """ Using an unknown shellType should raise NotImplementedError """ action = _shellcomp.SubcommandAction() self.assertRaises( NotImplementedError, action._shellCode, None, "bad_shell_type" ) class FighterAceServerOptions(usage.Options): """ Options for FighterAce 'server' subcommand """ optFlags = [ ["list-server", None, "List this server with the online FighterAce network"] ] optParameters = [ [ "packets-per-second", None, "Number of update packets to send per second", "20", ] ] class FighterAceOptions(usage.Options): """ Command-line options for an imaginary `Fighter Ace` game """ optFlags: List[List[Optional[str]]] = [ ["fokker", "f", "Select the Fokker Dr.I as your dogfighter aircraft"], ["albatros", "a", "Select the Albatros D-III as your dogfighter aircraft"], ["spad", "s", "Select the SPAD S.VII as your dogfighter aircraft"], ["bristol", "b", "Select the Bristol Scout as your dogfighter aircraft"], ["physics", "p", "Enable secret Twisted physics engine"], ["jam", "j", "Enable a small chance that your machine guns will jam!"], ["verbose", "v", "Verbose logging (may be specified more than once)"], ] optParameters: List[List[Optional[str]]] = [ ["pilot-name", None, "What's your name, Ace?", "Manfred von Richthofen"], ["detail", "d", "Select the level of rendering detail (1-5)", "3"], ] subCommands = [ ["server", None, FighterAceServerOptions, "Start FighterAce game-server."], ] compData = Completions( descriptions={"physics": "Twisted-Physics", "detail": "Rendering detail level"}, multiUse=["verbose"], mutuallyExclusive=[["fokker", "albatros", "spad", "bristol"]], optActions={"detail": CompleteList(["1" "2" "3" "4" "5"])}, extraActions=[CompleteFiles(descr="saved game file to load")], ) def opt_silly(self): # A silly option which nobody can explain """ """ class FighterAceExtendedOptions(FighterAceOptions): """ Extend the options and zsh metadata provided by FighterAceOptions. _shellcomp must accumulate options and metadata from all classes in the hiearchy so this is important to test. """ optFlags = [["no-stalls", None, "Turn off the ability to stall your aircraft"]] optParameters = [ ["reality-level", None, "Select the level of physics reality (1-5)", "5"] ] compData = Completions( descriptions={"no-stalls": "Can't stall your plane"}, optActions={"reality-level": Completer(descr="Physics reality level")}, ) def opt_nocrash(self): """ Select that you can't crash your plane """ def opt_difficulty(self, difficulty): """ How tough are you? (1-10) """ def _accuracyAction(): # add tick marks just to exercise quoting return CompleteList(["1", "2", "3"], descr="Accuracy'`?") class SimpleProgOptions(usage.Options): """ Command-line options for a `Silly` imaginary program """ optFlags = [ ["color", "c", "Turn on color output"], ["gray", "g", "Turn on gray-scale output"], ["verbose", "v", "Verbose logging (may be specified more than once)"], ] optParameters = [ ["optimization", None, "5", "Select the level of optimization (1-5)"], ["accuracy", "a", "3", "Select the level of accuracy (1-3)"], ] compData = Completions( descriptions={"color": "Color on", "optimization": "Optimization level"}, multiUse=["verbose"], mutuallyExclusive=[["color", "gray"]], optActions={ "optimization": CompleteList( ["1", "2", "3", "4", "5"], descr="Optimization?" ), "accuracy": _accuracyAction, }, extraActions=[CompleteFiles(descr="output file")], ) def opt_X(self): """ usage.Options does not recognize single-letter opt_ methods """ class SimpleProgSub1(usage.Options): optFlags = [["sub-opt", "s", "Sub Opt One"]] class SimpleProgSub2(usage.Options): optFlags = [["sub-opt", "s", "Sub Opt Two"]] class SimpleProgWithSubcommands(SimpleProgOptions): optFlags = [["some-option"], ["other-option", "o"]] optParameters = [ ["some-param"], ["other-param", "p"], ["another-param", "P", "Yet Another Param"], ] subCommands = [ ["sub1", None, SimpleProgSub1, "Sub Command 1"], ["sub2", None, SimpleProgSub2, "Sub Command 2"], ] testOutput1 = b"""#compdef silly _arguments -s -A "-*" \\ ':output file (*):_files -g "*"' \\ "(--accuracy)-a[Select the level of accuracy (1-3)]:Accuracy'\\`?:(1 2 3)" \\ "(-a)--accuracy=[Select the level of accuracy (1-3)]:Accuracy'\\`?:(1 2 3)" \\ '(--color --gray -g)-c[Color on]' \\ '(--gray -c -g)--color[Color on]' \\ '(--color --gray -c)-g[Turn on gray-scale output]' \\ '(--color -c -g)--gray[Turn on gray-scale output]' \\ '--help[Display this help and exit.]' \\ '--optimization=[Optimization level]:Optimization?:(1 2 3 4 5)' \\ '*-v[Verbose logging (may be specified more than once)]' \\ '*--verbose[Verbose logging (may be specified more than once)]' \\ '--version[Display Twisted version and exit.]' \\ && return 0 """ # with sub-commands testOutput2 = b"""#compdef silly2 _arguments -s -A "-*" \\ '*::subcmd:->subcmd' \\ ':output file (*):_files -g "*"' \\ "(--accuracy)-a[Select the level of accuracy (1-3)]:Accuracy'\\`?:(1 2 3)" \\ "(-a)--accuracy=[Select the level of accuracy (1-3)]:Accuracy'\\`?:(1 2 3)" \\ '(--another-param)-P[another-param]:another-param:_files' \\ '(-P)--another-param=[another-param]:another-param:_files' \\ '(--color --gray -g)-c[Color on]' \\ '(--gray -c -g)--color[Color on]' \\ '(--color --gray -c)-g[Turn on gray-scale output]' \\ '(--color -c -g)--gray[Turn on gray-scale output]' \\ '--help[Display this help and exit.]' \\ '--optimization=[Optimization level]:Optimization?:(1 2 3 4 5)' \\ '(--other-option)-o[other-option]' \\ '(-o)--other-option[other-option]' \\ '(--other-param)-p[other-param]:other-param:_files' \\ '(-p)--other-param=[other-param]:other-param:_files' \\ '--some-option[some-option]' \\ '--some-param=[some-param]:some-param:_files' \\ '*-v[Verbose logging (may be specified more than once)]' \\ '*--verbose[Verbose logging (may be specified more than once)]' \\ '--version[Display Twisted version and exit.]' \\ && return 0 local _zsh_subcmds_array _zsh_subcmds_array=( "sub1:Sub Command 1" "sub2:Sub Command 2" ) _describe "sub-command" _zsh_subcmds_array """