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 = ["pytest-mock (>=3,<4)"] }
 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 pytest_mock import MockerFixture
 
 from common.test_tools.types import AssertMetricFixture
 
@@ -32,3 +33,22 @@ def _assert_metric(
 
 
 assert_metric = pytest.fixture(assert_metric_impl)
+
+
+@pytest.fixture()
+def saas_mode(mocker: MockerFixture) -> None:
+    mocker.patch("common.core.utils.is_saas", return_value=True)
+
+
+@pytest.fixture()
+def enterprise_mode(mocker: MockerFixture) -> None:
+    mocker.patch("common.core.utils.is_enterprise", return_value=True)
+
+
+@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

@@ -37,3 +37,21 @@ def test_assert_metrics__registry_reset_expected(
             labels={"test_name": "test_assert_metrics__registry_reset_expected"},
             value=1,
         )
+
+
+@pytest.mark.saas_mode
+def test_saas_mode_marker__is_saas_returns_expected() -> None:
+    # Given
+    from common.core.utils import is_saas
+
+    # When & Then
+    assert is_saas() is True
+
+
+@pytest.mark.enterprise_mode
+def test_enterprise_mode_marker__is_enterprise_returns_expected() -> None:
+    # Given
+    from common.core.utils import is_enterprise
+
+    # When & Then
+    assert is_enterprise() is True