Locally test a plugin during development?

Get Help
1

I’m writing a few plugins for a customer, for now on the customer’s system (we may contribute them later).

I’ve created a rough skeleton of the first plugin, with DOCUMENTATION, EXAMPLES, RETURN and (it’s a test plugin) a TestModule class and a function (that only returns False statically, for now). Now I want to be able to test that locally.

AIUI, ansible-test sanity should run the tests from the EXAMPLES section, is this correct?

However, I cannot get it to work locally. I’m in the directory …/ansible_collections/local/custname/ and try:

$ ansible-test sanity --local --python-interpreter /usr/bin/python3 plugins/test/ip_compare.py
Running sanity test "action-plugin-docs"
Running sanity test "ansible-doc"
Installing requirements for Python 3.13 [venv]
Downloading pip 24.2 bootstrap script: https://ci-files.testing.ansible.com/ansible-test/get-pip-24.2.py
Download failed: <urlopen error [Errno 101] Network is unreachable>
 
The bootstrap script can be manually downloaded and saved to: …/.ansible/test/cache/get_pip_24_2.py
 
If you're behind a proxy, consider commenting on the following GitHub issue:
 
https://github.com/ansible/ansible/issues/77304
FATAL: Python 3.13 at "…/.ansible/test/venv/sanity.ansible-doc/3.13/faf00c3c/bin/python" does not have pip available.

I thought the --local option should make it so it does NOT use a venv, but here it tries to do that.

The system is indeed disconnected from the larger internet, but I can install additional Debian packages if needed. My local collection does not have any special requirements set.

There is no manpage for ansible-test, and the --help output is terse and only useful for those who already know what they’re doing.

tl;dr

So, the questions are:

  • does this indeed run the tests from EXAMPLES (and, if not, what does?)
  • how can I get that to run truly locally (as nōn-root (will suffice for these tests), using system Python3, etc.)?
2

By duplicating the EXAMPLES in tests/integration/targets/ip_compare/tasks/main.yml I made this work (with ansible-test integration ip_compare), but is that really the intended way?

3

No. sanity does not run any tests, it runs sanity checks. (Also no other ansible-test sub command runs anything from EXAMPLES. No other testing tool does either, to my knowlege.)

That only works (or worked?) with --docker, to my knowledge. For that you need to have the required container images available though.

Yes. EXAMPLES are not tests, and in 99.99% of all modules cannot be used as tests.

4

Ah, okay. I apparently happened to pick up the one or two as “template” where the EXAMPLES used assert as if they were testcases.

I’ll work with the split tests, thanks.