Hacking Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• hacking/README.md
• hacking/azp/incidental.py
• hacking/ticket_stubs/README.md
• hacking/ticket_stubs/bug_wrong_repo.md
• test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py
• AGENTS.md

The hacking/ directory contains a collection of scripts and tools designed to assist Ansible developers and maintainers. These utilities streamline common development tasks, such as setting up a development environment, testing modules in isolation, generating documentation, and managing community contributions. They are essential for ensuring code quality, consistency, and adherence to project standards.

This documentation provides an overview of the key scripts available in the hacking/ directory and related development tools, explaining their purpose and usage based on the repository's source files. These tools are integral to the Ansible development and contribution workflow.

Core Development Scripts

The hacking/ directory provides several scripts to aid in the development and testing of Ansible modules.

Sources: hacking/README.md

Script	Description
env-setup	Modifies the shell environment to allow running Ansible directly from a Git checkout.
test-module.py	Allows developers to run a single Ansible module locally, outside of the main ansible program.
return_skeleton_generator.py	Helps generate the RETURNS section for module documentation from the JSON output of a module run.

Sources: hacking/README.md:4-48

env-setup

This script configures the current shell session to use the Ansible source code from the Git checkout. It must be sourced to take effect.

Usage:

source ./hacking/env-setup

After sourcing the script, developers may need to install prerequisites using pip.

pip install -r requirements.txt

Sources: hacking/README.md:7-17

test-module.py

This utility provides a simple way to execute a module on the local machine for testing and debugging purposes. It accepts the module path and arguments.

Usage:

# Simple arguments
./hacking/test-module.py -m lib/ansible/modules/command.py -a "echo hi"

# Complex JSON arguments
./hacking/test-module.py -m module \
  -a '{"parent": {"child": [{"item": "first", "val": "foo"}, {"item": "second", "val": "bar"}]}}'

This is particularly useful for inserting breakpoints into a module for debugging.

The following diagram illustrates the execution flow of the test-module.py script.

Test Coverage Reporting

The hacking/azp/incidental.py script is a command-line tool for reporting on incidental test coverage by analyzing data downloaded from Azure Pipelines.

Sources: hacking/azp/incidental.py

Purpose

The script processes code coverage reports to identify which lines of code are covered by specific integration tests. It can be used in two main modes:

1. Exclusive Coverage: Report on code coverage that is exclusive to a set of test targets (e.g., incidental_* tests).
2. Missing Coverage: Report on code coverage for a specific plugin that is missing from its dedicated integration test.

Sources: hacking/azp/incidental.py:118-133

Execution Flow

The script follows a multi-step process to generate its reports. It combines raw coverage data, filters it based on specified targets, compares coverage sets, and finally generates human-readable reports.

This diagram shows the high-level workflow of the incidental.py script.

Key Components

The script is composed of several classes that manage different aspects of the reporting process.

Class	Responsibility
CoverageTool	A wrapper around ansible-test coverage analyze targets commands like combine, filter, and missing.
Git	An interface for running git commands to retrieve source file content from a specific commit.
CoverageData	Parses run.json from the Azure Pipelines results to get the commit SHA and test status.
SourceFile	Represents a single source file, holding its content and the specific lines/arcs covered by a test.

Sources: hacking/azp/incidental.py:227-313

Module and Plugin Validation

A critical part of the development process is ensuring that new or modified modules and plugins adhere to Ansible's standards. The validate-modules sanity test is a key tool for this.

Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py

validate-modules Script

This script is the engine behind the ansible-test sanity --test validate-modules command. It performs a wide range of static checks on module and plugin files.

The main execution flow involves parsing arguments, iterating through specified plugin files, and using a ModuleValidator instance for each file to run checks and report errors or warnings.

Key Validation Checks

The ModuleValidator class implements numerous checks, including:

• Licensing: Verifies the presence of a GPLv3 license header.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:365-379
• Interpreter Shebang: Ensures Python modules start with #!/usr/bin/python and PowerShell modules with #!powershell.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:341-363
• Forbidden Calls: Detects direct use of sys.exit(), subprocess.Popen, and os.call(), which should be replaced by module.fail_json() or module.run_command().
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:381-417
• Documentation Schema: Validates the structure of DOCUMENTATION, EXAMPLES, and RETURN blocks against a defined schema.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:608-641
• Argument Spec Consistency: Compares the argument_spec in the code with the options defined in the DOCUMENTATION block to ensure they match in terms of names, types, defaults, and required status.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:910-1216
• Import Order: Checks that Python imports appear after the documentation blocks.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:488-537
• Deprecation Consistency: Ensures that deprecation information in meta/runtime.yml matches the deprecated field in the module's documentation.
  Sources: test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:771-819

Validator Class Structure

The validation logic is encapsulated in validator classes. The base Validator class is abstract, with ModuleValidator providing the specific implementation for Ansible plugins.

This diagram shows the class structure for the validators.

GitHub Ticket Stubs

The hacking/ticket_stubs/ directory contains templates for common responses to GitHub issues. This helps maintainers save time and provide consistent feedback when managing the high volume of tickets.

For example, bug_wrong_repo.md is a template used to inform a user that their issue has been filed in the wrong repository and directs them to the correct location.

Sources: hacking/ticket_stubs/README.md, hacking/ticket_stubs/bug_wrong_repo.md

AI Agent Guidance

The AGENTS.md file provides specific instructions for AI assistants working with the Ansible repository. It outlines critical requirements, common commands, and standard procedures to ensure that AI-generated contributions align with project standards.

Key instructions include:

• Licensing Requirements: All code for ansible-core must be GPLv3 compatible. This is a non-negotiable requirement.
• Testing Commands: Standard ansible-test commands for running sanity, unit, and integration tests.
• PR Review Process: A checklist for reviewing pull requests, including checking for changelogs and appropriate tests.
• Code Style: Notes on line limits (160 characters), import placement, and type hinting.

Sources: AGENTS.md:1-20, 28-50, 95-122, 124-135