diff --git a/hacking/test-module.py b/hacking/test-module.py index a9df1a79b8f..b24cc75e047 100755 --- a/hacking/test-module.py +++ b/hacking/test-module.py @@ -1,32 +1,10 @@ #!/usr/bin/env python # (c) 2012, Michael DeHaan -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . -# - -# this script is for testing modules without running through the -# entire guts of ansible, and is very helpful for when developing -# modules -# -# example: -# ./hacking/test-module.py -m lib/ansible/modules/command.py -a "/bin/sleep 3" -# ./hacking/test-module.py -m lib/ansible/modules/command.py -a "/bin/sleep 3" --debugger /usr/bin/pdb -# ./hacking/test-module.py -m lib/ansible/modules/lineinfile.py -a "dest=/etc/exports line='/srv/home hostname1(rw,sync)'" --check -# ./hacking/test-module.py -m lib/ansible/modules/command.py -a "echo hello" -n -o "test_hello" +# This file is part of Ansible, a free software under the GNU General Public License + +# This script is for testing Ansible modules without going through the entire Ansible engine. +# It helps developers test modules directly. Example usage is provided in the comments above. from __future__ import annotations @@ -37,7 +15,6 @@ import subprocess import sys import traceback import shutil - from pathlib import Path from ansible.release import __version__ @@ -54,6 +31,7 @@ from ansible.template import Templar import json +## Parse command-line arguments for testing the Ansible module def parse(): """parse command line @@ -89,6 +67,7 @@ def parse(): return options, args +## Write module arguments to a file (old-style module's use) def write_argsfile(argstring, json=False): """ Write args to a file for old-style module's use. """ argspath = Path("~/.ansible_test_module_arguments").expanduser() @@ -99,6 +78,7 @@ def write_argsfile(argstring, json=False): return argspath +## Get the interpreters for running the module, ensuring proper format def get_interpreters(interpreter): result = dict() if interpreter: @@ -114,18 +94,11 @@ def get_interpreters(interpreter): return result +## Simulate Ansible's process to set up the module for testing def boilerplate_module(modfile, args, interpreters, check, destfile): """ simulate what ansible does with new style modules """ - - # module_fh = open(modfile) - # module_data = module_fh.read() - # module_fh.close() - - # replacer = module_common.ModuleReplacer() loader = DataLoader() - # included_boilerplate = module_data.find(module_common.REPLACER) != -1 or module_data.find("import ansible.module_utils") != -1 - complex_args = {} # default selinux fs list is pass in as _ansible_selinux_special_fs arg @@ -134,15 +107,15 @@ def boilerplate_module(modfile, args, interpreters, check, destfile): complex_args['_ansible_keep_remote_files'] = C.DEFAULT_KEEP_REMOTE_FILES complex_args['_ansible_version'] = __version__ + # Load arguments if they are in YAML/JSON format if args.startswith("@"): - # Argument is a YAML file (JSON is a subset of YAML) complex_args = utils_vars.combine_vars(complex_args, loader.load_from_file(args[1:])) args = '' elif args.startswith("{"): - # Argument is a YAML document (not a file) complex_args = utils_vars.combine_vars(complex_args, loader.load(args)) args = '' + # Add parsed arguments to the module execution if args: parsed_args = parse_kv(args) complex_args = utils_vars.combine_vars(complex_args, parsed_args) @@ -176,6 +149,7 @@ def boilerplate_module(modfile, args, interpreters, check, destfile): return (modfile2_path, modname, module_style) +## Extract and setup an AnsiBallZ module for execution def ansiballz_setup(modfile, modname, interpreters): os.system("chmod +x %s" % modfile) @@ -196,11 +170,10 @@ def ansiballz_setup(modfile, modname, interpreters): sys.exit(err) debug_dir = lines[1].strip() - # All the directories in an AnsiBallZ that modules can live core_dirs = glob.glob(os.path.join(debug_dir, 'ansible/modules')) collection_dirs = glob.glob(os.path.join(debug_dir, 'ansible_collections/*/*/plugins/modules')) - # There's only one module in an AnsiBallZ payload so look for the first module and then exit + # Find and return the module for module_dir in core_dirs + collection_dirs: for dirname, directories, filenames in os.walk(module_dir): for filename in filenames: @@ -214,6 +187,7 @@ def ansiballz_setup(modfile, modname, interpreters): return modfile, argsfile +## Execute the test on the module, running it and piping its output def runtest(modfile, argspath, modname, module_style, interpreters): """Test run a module, piping it's output for reporting.""" invoke = "" @@ -250,6 +224,7 @@ def runtest(modfile, argspath, modname, module_style, interpreters): print(jsonify(results, format=True)) +## Debug the module with an interactive console debugger def rundebug(debugger, modfile, argspath, modname, module_style, interpreters): """Run interactively with console debugger.""" @@ -262,31 +237,33 @@ def rundebug(debugger, modfile, argspath, modname, module_style, interpreters): subprocess.call("%s %s" % (debugger, modfile), shell=True) -def main(): - +if __name__ == '__main__': options, args = parse() - init_plugin_loader() interpreters = get_interpreters(options.interpreter) - (modfile, modname, module_style) = boilerplate_module(options.module_path, options.module_args, interpreters, options.check, options.filename) - - argspath = None - if module_style not in ('new', 'ansiballz'): - if module_style in ('non_native_want_json', 'binary'): - argspath = write_argsfile(options.module_args, json=True) - elif module_style == 'old': - argspath = write_argsfile(options.module_args, json=False) - else: - raise Exception("internal error, unexpected module style: %s" % module_style) - - if options.execute: - if options.debugger: - rundebug(options.debugger, modfile, argspath, modname, module_style, interpreters) - else: - runtest(modfile, argspath, modname, module_style, interpreters) - + argspath = write_argsfile(options.module_args) + + modfile, modname, module_style = boilerplate_module( + options.module_path, + options.module_args, + interpreters, + options.check, + options.filename + ) -if __name__ == "__main__": - try: - main() - finally: - shutil.rmtree(C.DEFAULT_LOCAL_TMP, True) + if options.debugger: + rundebug( + options.debugger, + modfile, + argspath, + modname, + module_style, + interpreters + ) + elif options.execute: + runtest( + modfile, + argspath, + modname, + module_style, + interpreters + )