Consider an `iris.testing` module

[trexfeathers]

📰 Custom Issue

Analogous to numpy.testing - a module where we can share our testing conveniences publicly.

We are in the process of implementing iris.tests._shared_utils. Here it is on its feature branch:

https://github.com/SciTools/iris/blob/00f0e0c838e5b6415b584b92c4e2c5c6221af00d/lib/iris/tests/_shared_utils.py#L5

iris.tests._shared_utils contains the conveniences that originally belonged to the iris.tests.IrisTest class, which is going to be deprecated once we complete our move to PyTest. I think ideally this could become the iris.testing module.

Motivating factors

1. The documentation we are writing in #5785 makes many references to this module, which of course isn't documented since it's within iris.tests and is private. It would be more helpful if in a public module, which would mean the references have something to link to.

2. We know that we have users who use the conveniences in IrisTest / _shared_utils and find them very valuable. This is currently a rather loose contract since they are in private areas of the codebase. I think it would be good to make the conveniences explicitly open to use, although that may only be appropriate once we have finished the PyTest migration and learned all our lessons. If we're not comfortable with fully maintaining stable API we could perhaps incorporate some sort of warning that the code is subject to change?

[bjlittle]

The only major downside of this is that we'd then need to "officially" support it.

Without getting all meta, are you proposing that we also test out testing infrastructure?

[trexfeathers]

The only major downside of this is that we'd then need to "officially" support it.

Without getting all meta, are you proposing that we also test out testing infrastructure?

Agreed, it's not a slam dunk by any means.

And yes we would need to test things like assert_CDL if we went for this.

[rcomer]

For (1), it is possible to document private modules https://matplotlib.org/stable/api/_api_api.html

[ESadek-MO]

After a discussion with testing lead and buddies:

The testing convenience module should be private, with a contract of "this is subject to change, use at your own risk". Although we don't forsee any immediate changes, we don't want to officially support the module.