feat(test-tools): SaaS/Enterprise mode markers, update documentation (#53)

* feat(test-tools): SaaS/Enterprise mode markers, update documentation

Author: khvn26

README.md

@@ -46,13 +46,56 @@ make install-packages opts="--extras 'feature1 feature2'"
 
 #### Installation
 
-1. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
+1. To make use of the `test_tools` Pytest plugin, install the packages with the `test-tools` extra, e.g. `pip install flagsmith-common[test-tools]`.
+
+2. Make sure `"common.core"` is in the `INSTALLED_APPS` of your settings module.
 This enables the `manage.py flagsmith` commands.
 
-2. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
+3. Add `"common.gunicorn.middleware.RouteLoggerMiddleware"` to `MIDDLEWARE` in your settings module.
 This enables the `route` label for Prometheus HTTP metrics.
 
-3. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+4. To enable the `/metrics` endpoint, set the `PROMETHEUS_ENABLED` setting to `True`.
+
+#### Test tools
+
+##### Fixtures
+
+###### `assert_metric`
+
+To test your metrics using the `assert_metric` fixture:
+
+```python
+from common.test_tools import AssertMetricFixture
+
+def test_my_code__expected_metrics(assert_metric: AssertMetricFixture) -> None:
+    # When
+    my_code()
+
+    # Then
+    assert_metric(
+        name="flagsmith_distance_from_earth_au_sum",
+        labels={"engine_type": "solar_sail"},
+        value=1.0,
+    )
+```
+
+###### `saas_mode`
+
+The `saas_mode` fixture makes all `common.core.utils.is_saas` calls return `True`.
+
+###### `enterprise_mode`
+
+The `enterprise_mode` fixture makes all `common.core.utils.is_enterprise` calls return `True`.
+
+##### Markers
+
+###### `pytest.mark.saas_mode`
+
+Use this mark to auto-use the `saas_mode` fixture.
+
+###### `pytest.mark.enterprise_mode`
+
+Use this mark to auto-use the `enterprise_mode` fixture.
 
 #### Metrics
 
@@ -87,14 +130,18 @@ It's generally a good idea to allow users to define histogram buckets of their o
 import prometheus_client
 from django.conf import settings
 
-flagsmith_distance_from_earth_au = prometheus.Histogram(
+flagsmith_distance_from_earth_au = prometheus_client.Histogram(
     "flagsmith_distance_from_earth_au",
     "Distance from Earth in astronomical units",
+    labels=["engine_type"],
     buckets=settings.DISTANCE_FROM_EARTH_AU_HISTOGRAM_BUCKETS,
 )
 ```
 
+For testing your metrics, refer to [`assert_metric` documentation][5].
+
 [1]: https://prometheus.io/docs/practices/naming/
 [2]: https://github.com/Flagsmith/flagsmith-common/blob/main/src/common/gunicorn/metrics.py
 [3]: https://docs.gunicorn.org/en/stable/design.html#server-model
 [4]: https://prometheus.github.io/client_python/multiprocess
+[5]: #assert_metric

poetry.lock

@@ -18,6 +18,7 @@ dependencies = [
     "psycopg2-binary (>=2.9,<3)",
     "simplejson (>=3,<4)",
 ]
+optional-dependencies = { test-tools = ["pyfakefs (>=5,<6)"] }
 authors = [
     { name = "Matthew Elwell" },
     { name = "Gagan Trivedi" },

pyproject.toml

@@ -3,6 +3,7 @@
 import prometheus_client
 import pytest
 from prometheus_client.metrics import MetricWrapperBase
+from pyfakefs.fake_filesystem import FakeFilesystem
 
 from common.test_tools.types import AssertMetricFixture
 
@@ -32,3 +33,38 @@ def _assert_metric(
 
 
 assert_metric = pytest.fixture(assert_metric_impl)
+
+
+@pytest.fixture()
+def saas_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+    from common.core.utils import is_saas
+
+    is_saas.cache_clear()
+    fs.create_file("./SAAS_DEPLOYMENT")
+
+    yield
+
+    is_saas.cache_clear()
+
+
+@pytest.fixture()
+def enterprise_mode(fs: FakeFilesystem) -> Generator[None, None, None]:
+    from common.core.utils import is_enterprise
+
+    is_enterprise.cache_clear()
+    fs.create_file("./ENTERPRISE_VERSION")
+
+    yield
+
+    is_enterprise.cache_clear()
+
+
+@pytest.fixture(autouse=True)
+def flagsmith_markers_marked(
+    request: pytest.FixtureRequest,
+) -> None:
+    for marker in request.node.iter_markers():
+        if marker.name == "saas_mode":
+            request.getfixturevalue("saas_mode")
+        if marker.name == "enterprise_mode":
+            request.getfixturevalue("enterprise_mode")

src/common/test_tools/plugin.py

@@ -0,0 +1,11 @@
+from typing import Literal
+
+from common.core.utils import is_enterprise, is_saas
+
+
+def edition_printer() -> Literal["saas!", "enterprise!", "oss!"]:
+    if is_saas():
+        return "saas!"
+    if is_enterprise():
+        return "enterprise!"
+    return "oss!"

src/common/test_tools/utils.py

@@ -3,6 +3,7 @@
 
 from common.test_tools import AssertMetricFixture
 from common.test_tools.plugin import assert_metric_impl
+from common.test_tools.utils import edition_printer
 
 
 def test_assert_metrics__asserts_expected(
@@ -37,3 +38,20 @@ def test_assert_metrics__registry_reset_expected(
             labels={"test_name": "test_assert_metrics__registry_reset_expected"},
             value=1,
         )
+
+
+def test_no_marker__oss_edition_expected() -> None:
+    # When & Then
+    assert edition_printer() == "oss!"
+
+
+@pytest.mark.saas_mode
+def test_saas_mode_marker__is_saas_returns_expected() -> None:
+    # When & Then
+    assert edition_printer() == "saas!"
+
+
+@pytest.mark.enterprise_mode
+def test_enterprise_mode_marker__is_enterprise_returns_expected() -> None:
+    # When & Then
+    assert edition_printer() == "enterprise!"