The arguments file is just a basic json config file that you can
use to pass the module your parameters to run the module it
Playbook module testing
=======================
If you want to test your new module, you can now consume it with an
Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
- Add the following to the new playbook file \`\`\`yaml ---
- name: test my new module connection: local hosts: localhost
tasks: - name: run the new module my\_new\_test\_module: name: 'hello'
new: true register: testout
::
- name: dump test output
debug:
msg: '{{ testout }}'
::
- Run the playbook and analyze the output: `$ ansible-playbook ./testmod.yml`
# Debugging (local)
If you want to break into a module and step through with the debugger, locally running the module you can do:
1. Set a breakpoint in the module: `import pdb; pdb.set_trace()`
1. Run the module on the local machine: `$ python -m pdb ./my_new_test_module.py ./args.json`
# Debugging (remote)
In the event you want to debug a module that is running on a remote target (i.e. not localhost), one way to do this is the following:
1. On your controller machine (running Ansible) set `ANSIBLE_KEEP_REMOTE_FILES=1` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them)
1. Run your playbook targetting the remote machine and specify `-vvvv` (the verbose output will show you many things, including the remote location that Ansible uses for the modules)
1. Take note of the remote path Ansible used on the remote host
1. SSH into the remote target after the completion of the playbook
1. Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: `~/.ansible/tmp/ansible-tmp-...`)
1. Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying `python my_test_module.py` (not necessary)
1. To debug, though, we will want to extra this zip out to the original module format: `python my_test_module.py explode` (Ansible will expand the module into `./debug-dir`)
1. Navigate to `./debug-dir` (notice that unzipping has caused the generation of `ansible_module_my_test_module.py`)
1. Modify or set a breakpoint in the unzipped module
1. Ensure that the unzipped module is executable: `$ chmod 755 ansible_module_my_test_module.py`
1. Run the unzipped module directly passing the args file: `$ ./ansible_module_my_test_module.py args` (args is the file that contains the params that were originally passed. Good for repro and debugging)
# Unit testing
Unit tests for modules will be appropriately located in `./test/units/modules`. You must first setup your testing environment. In my case, I'm using Python 3.5.
- Install the requirements (outside of your virtual environment): `$ pip3 install -r ./test/runner/requirements/units.txt`
- To run all tests do the following: `$ ansible-test units --python 3.5` (you must run `. hacking/env-setup` prior to this)
:bulb:Ansible uses pytest for unit testing
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
The arguments file is just a basic json config file that you can
use to pass the module your parameters to run the module it
Playbook module testing
=======================
If you want to test your new module, you can now consume it with an
Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
- Add the following to the new playbook file \`\`\`yaml ---
- name: test my new module connection: local hosts: localhost
tasks: - name: run the new module my\_new\_test\_module: name: 'hello'
new: true register: testout
::
- name: dump test output
debug:
msg: '{{ testout }}'
::
- Run the playbook and analyze the output: `$ ansible-playbook ./testmod.yml`
# Debugging (local)
If you want to break into a module and step through with the debugger, locally running the module you can do:
1. Set a breakpoint in the module: `import pdb; pdb.set_trace()`
1. Run the module on the local machine: `$ python -m pdb ./my_new_test_module.py ./args.json`
# Debugging (remote)
In the event you want to debug a module that is running on a remote target (i.e. not localhost), one way to do this is the following:
1. On your controller machine (running Ansible) set `ANSIBLE_KEEP_REMOTE_FILES=1` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them)
1. Run your playbook targetting the remote machine and specify `-vvvv` (the verbose output will show you many things, including the remote location that Ansible uses for the modules)
1. Take note of the remote path Ansible used on the remote host
1. SSH into the remote target after the completion of the playbook
1. Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: `~/.ansible/tmp/ansible-tmp-...`)
1. Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying `python my_test_module.py` (not necessary)
1. To debug, though, we will want to extra this zip out to the original module format: `python my_test_module.py explode` (Ansible will expand the module into `./debug-dir`)
1. Navigate to `./debug-dir` (notice that unzipping has caused the generation of `ansible_module_my_test_module.py`)
1. Modify or set a breakpoint in the unzipped module
1. Ensure that the unzipped module is executable: `$ chmod 755 ansible_module_my_test_module.py`
1. Run the unzipped module directly passing the args file: `$ ./ansible_module_my_test_module.py args` (args is the file that contains the params that were originally passed. Good for repro and debugging)
# Unit testing
Unit tests for modules will be appropriately located in `./test/units/modules`. You must first setup your testing environment. In my case, I'm using Python 3.5.
- Install the requirements (outside of your virtual environment): `$ pip3 install -r ./test/runner/requirements/units.txt`
- To run all tests do the following: `$ ansible-test units --python 3.5` (you must run `. hacking/env-setup` prior to this)
:bulb:Ansible uses pytest for unit testing
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
Join the IRC channel ``#ansible-devel`` on freenode for discussions
surrounding Ansible development.
For questions and discussions pertaining to using the Ansible product,
use the ``#ansible`` channel.
Credit
======
A *huge* thank you to the Ansible team at Red Hat for providing not only
a great product but also the willingness to help out contributors!are going to use Python here but any language is possible. Only File I/O and outputting to standard
outAnsible Development by Example
==============================
-`Why? <#why>`__
-`What is this? <#what-is-this>`__
-`Environment setup <#environment-setup>`__
-`New module development <#new-module-development>`__
The arguments file is just a basic json config file that you can
use to pass the module your parameters to run the module it
Playbook module testing
=======================
If you want to test your new module, you can now consume it with an
Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
- Add the following to the new playbook file \`\`\`yaml ---
- name: test my new module connection: local hosts: localhost
tasks: - name: run the new module my\_new\_test\_module: name: 'hello'
new: true register: testout
::
- name: dump test output
debug:
msg: '{{ testout }}'
::
- Run the playbook and analyze the output: `$ ansible-playbook ./testmod.yml`
# Debugging (local)
If you want to break into a module and step through with the debugger, locally running the module you can do:
1. Set a breakpoint in the module: `import pdb; pdb.set_trace()`
1. Run the module on the local machine: `$ python -m pdb ./my_new_test_module.py ./args.json`
# Debugging (remote)
In the event you want to debug a module that is running on a remote target (i.e. not localhost), one way to do this is the following:
1. On your controller machine (running Ansible) set `ANSIBLE_KEEP_REMOTE_FILES=1` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them)
1. Run your playbook targetting the remote machine and specify `-vvvv` (the verbose output will show you many things, including the remote location that Ansible uses for the modules)
1. Take note of the remote path Ansible used on the remote host
1. SSH into the remote target after the completion of the playbook
1. Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: `~/.ansible/tmp/ansible-tmp-...`)
1. Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying `python my_test_module.py` (not necessary)
1. To debug, though, we will want to extra this zip out to the original module format: `python my_test_module.py explode` (Ansible will expand the module into `./debug-dir`)
1. Navigate to `./debug-dir` (notice that unzipping has caused the generation of `ansible_module_my_test_module.py`)
1. Modify or set a breakpoint in the unzipped module
1. Ensure that the unzipped module is executable: `$ chmod 755 ansible_module_my_test_module.py`
1. Run the unzipped module directly passing the args file: `$ ./ansible_module_my_test_module.py args` (args is the file that contains the params that were originally passed. Good for repro and debugging)
# Unit testing
Unit tests for modules will be appropriately located in `./test/units/modules`. You must first setup your testing environment. In my case, I'm using Python 3.5.
- Install the requirements (outside of your virtual environment): `$ pip3 install -r ./test/runner/requirements/units.txt`
- To run all tests do the following: `$ ansible-test units --python 3.5` (you must run `. hacking/env-setup` prior to this)
:bulb:Ansible uses pytest for unit testing
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
The arguments file is just a basic json config file that you can
use to pass the module your parameters to run the module it
Playbook module testing
=======================
If you want to test your new module, you can now consume it with an
Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
- Add the following to the new playbook file \`\`\`yaml ---
- name: test my new module connection: local hosts: localhost
tasks: - name: run the new module my\_new\_test\_module: name: 'hello'
new: true register: testout
::
- name: dump test output
debug:
msg: '{{ testout }}'
::
- Run the playbook and analyze the output: `$ ansible-playbook ./testmod.yml`
# Debugging (local)
If you want to break into a module and step through with the debugger, locally running the module you can do:
1. Set a breakpoint in the module: `import pdb; pdb.set_trace()`
1. Run the module on the local machine: `$ python -m pdb ./my_new_test_module.py ./args.json`
# Debugging (remote)
In the event you want to debug a module that is running on a remote target (i.e. not localhost), one way to do this is the following:
1. On your controller machine (running Ansible) set `ANSIBLE_KEEP_REMOTE_FILES=1` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them)
1. Run your playbook targetting the remote machine and specify `-vvvv` (the verbose output will show you many things, including the remote location that Ansible uses for the modules)
1. Take note of the remote path Ansible used on the remote host
1. SSH into the remote target after the completion of the playbook
1. Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: `~/.ansible/tmp/ansible-tmp-...`)
1. Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying `python my_test_module.py` (not necessary)
1. To debug, though, we will want to extra this zip out to the original module format: `python my_test_module.py explode` (Ansible will expand the module into `./debug-dir`)
1. Navigate to `./debug-dir` (notice that unzipping has caused the generation of `ansible_module_my_test_module.py`)
1. Modify or set a breakpoint in the unzipped module
1. Ensure that the unzipped module is executable: `$ chmod 755 ansible_module_my_test_module.py`
1. Run the unzipped module directly passing the args file: `$ ./ansible_module_my_test_module.py args` (args is the file that contains the params that were originally passed. Good for repro and debugging)
# Unit testing
Unit tests for modules will be appropriately located in `./test/units/modules`. You must first setup your testing environment. In my case, I'm using Python 3.5.
- Install the requirements (outside of your virtual environment): `$ pip3 install -r ./test/runner/requirements/units.txt`
- To run all tests do the following: `$ ansible-test units --python 3.5` (you must run `. hacking/env-setup` prior to this)
:bulb:Ansible uses pytest for unit testing
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
The arguments file is just a basic json config file that you can
use to pass the module your parameters to run the module it
Playbook module testing
=======================
If you want to test your new module, you can now consume it with an
Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
- Add the following to the new playbook file \`\`\`yaml ---
- name: test my new module connection: local hosts: localhost
tasks: - name: run the new module my\_new\_test\_module: name: 'hello'
new: true register: testout
::
- name: dump test output
debug:
msg: '{{ testout }}'
::
- Run the playbook and analyze the output: `$ ansible-playbook ./testmod.yml`
# Debugging (local)
If you want to break into a module and step through with the debugger, locally running the module you can do:
1. Set a breakpoint in the module: `import pdb; pdb.set_trace()`
1. Run the module on the local machine: `$ python -m pdb ./my_new_test_module.py ./args.json`
# Debugging (remote)
In the event you want to debug a module that is running on a remote target (i.e. not localhost), one way to do this is the following:
1. On your controller machine (running Ansible) set `ANSIBLE_KEEP_REMOTE_FILES=1` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them)
1. Run your playbook targetting the remote machine and specify `-vvvv` (the verbose output will show you many things, including the remote location that Ansible uses for the modules)
1. Take note of the remote path Ansible used on the remote host
1. SSH into the remote target after the completion of the playbook
1. Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: `~/.ansible/tmp/ansible-tmp-...`)
1. Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying `python my_test_module.py` (not necessary)
1. To debug, though, we will want to extra this zip out to the original module format: `python my_test_module.py explode` (Ansible will expand the module into `./debug-dir`)
1. Navigate to `./debug-dir` (notice that unzipping has caused the generation of `ansible_module_my_test_module.py`)
1. Modify or set a breakpoint in the unzipped module
1. Ensure that the unzipped module is executable: `$ chmod 755 ansible_module_my_test_module.py`
1. Run the unzipped module directly passing the args file: `$ ./ansible_module_my_test_module.py args` (args is the file that contains the params that were originally passed. Good for repro and debugging)
# Unit testing
Unit tests for modules will be appropriately located in `./test/units/modules`. You must first setup your testing environment. In my case, I'm using Python 3.5.
- Install the requirements (outside of your virtual environment): `$ pip3 install -r ./test/runner/requirements/units.txt`
- To run all tests do the following: `$ ansible-test units --python 3.5` (you must run `. hacking/env-setup` prior to this)
:bulb:Ansible uses pytest for unit testing
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
