Mock get_platform / add CHARMHELPERS_IN_UNITTEST

Patch osplatform.get_platform() to return "ubuntu" if the environment
variable CHARMHELPERS_IN_UNITTEST is set to something truthy. This is to
enable unit testing in classic charms on NON ubuntu systems (e.g. Debian
bookworm) where the function is often called via a decorator that is
evaluated at module load time and thus is very, very tricky to mock out,
as it is often 'hit' during the test discovery phase.

README.rst

@@ -36,6 +36,19 @@ Dev/Test
 
 See the HACKING.md file for information about testing and development.
 
+Unit Test Mode
+==============
+
+If the environment variable `CHARMHELPERS_IN_UNITTEST` is set to a truthy value
+(e.g. 'on', 'true', 'anything') then then `osplatform.get_platform()` will
+*always* return `ubuntu`. This prevents it from attempting to call into
+platform libraries. This is needed as many charms try to call this function
+during module loading (via function decorators) and this makes it very
+difficult to mock out.
+
+Set this variable in the `tox.ini` of the charm using the `setenv` parameter in
+a testenv.
+
 License
 =======
 

charmhelpers/osplatform.py

@@ -2,7 +2,7 @@
 import os
 
 
-def get_platform():
+def _get_platform():
     """Return the current OS platform.
 
     For example: if current os platform is Ubuntu then a string "ubuntu"
@@ -47,3 +47,10 @@ def _get_platform_from_fs():
     for k, v in content.items():
         content[k] = v.strip('"')
     return content["NAME"]
+
+
+## If the unit-test mode is set, the platform is always "ubuntu"
+if not os.environ.get('CHARMHELPERS_IN_UNITTEST', False):
+    get_platform = _get_platform
+else:
+    get_platform = lambda: "ubuntu"