How do I run ansible-test on the root of my collection?

Question

I'm currently developing my own Ansible collection and following the documentation. The directory structure looks like this:

~/.ansible/collections/gertvdijk/mycollection
├── galaxy.yml
├── plugins
│   └── lookup
│       └── mylookup.py
├── README.md
└── tests
    └── unit
        └── plugins
            └── lookup
                └── test_mylookup.py

The location ~/.ansible/collections/gertvdijk/mycollection is chosen for convenience so that it's found on the default search paths for collections (COLLECTIONS_PATHS).

The Ansible developer document section Testing collections mentions that I should use ansible-test command from the root of my collection with the given structure.

You must always execute ansible-test from the root directory of a collection.

However, that fails to me, with an error as if I should use this in a project already.
Even running --help fails with the current working directory error:

$ ansible-test --help
ERROR: The current working directory must be at or below:

 - an Ansible collection: {...}/ansible_collections/{namespace}/{collection}/

Current working directory: /home/gert/.ansible/collections/gertvdijk/mycollection

Same thing happens by cloning an existing community collection (e.g. community.grafana). The GitHub CI steps include an installation in a ansible_collections/{namespace}/{collection} path (seen here).

Taking that as a work-around for now (I'd like to avoid that); move the repository of the collection to some path that includes /ansible_collections/gertvdijk/mycollection and then run it from there.

This can't be true, right, that the directory name two levels up make or break the ansible-test tool? What am I missing here?

Answer 1

TL;DR: The path for your home collection should be /home/gert/.ansible/collections/ansible_collections/gertvdijk/mycollection

---

The directories listed in COLLECTION_PATH are actually expected to contain a top level ansible_collections folder. This is linked to the ansible_collections convention used by e.g. module_utils as explained in the documentation

You can also observe how a blank folder gets structured by running e.g.

ansible-galaxy collection install -p /whatever community.grafana

In this case, you will end up with the folder /whatever/ansible_collections/community/grafana.

So your actual home folder collection path should be /home/gert/.ansible/collections/ansible_collections/gertvdijk/mycollection