CasperSecurity
# 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
"""