feat testsuite: add sample and docs for uservice_oneshot

Tests: протестировано CI
commit_hash:2e3bcf78374fb525511fd9bcf314f93ca53322c8

Author: apolukhin

samples/testsuite-support/tests/test_metrics.py

@@ -1,3 +1,6 @@
+import pytest
+
+
 async def test_basic(service_client, monitor_client):
     response = await service_client.get('/metrics')
     assert response.status_code == 200
@@ -7,6 +10,14 @@ async def test_basic(service_client, monitor_client):
     assert metric.value > 0
 
 
+# /// [uservice_oneshot sample]
+@pytest.mark.uservice_oneshot
+async def test_initial_metrics(service_client, monitor_client):
+    metric = await monitor_client.single_metric('sample-metrics.foo')
+    assert metric.value == 0
+    # /// [uservice_oneshot sample]
+
+
 # /// [metrics reset]
 async def test_reset(service_client, monitor_client):
     # Reset service metrics

scripts/docs/en/userver/functional_testing.md

@@ -195,11 +195,11 @@ In order to use it you need to register corresponding components:
 
 Headers:
 
-@snippet samples/testsuite-support/src/main.cpp testsuite - include components
+@snippet samples/testsuite-support/main.cpp testsuite - include components
 
 Add components to components list:
 
-@snippet samples/testsuite-support/src/main.cpp testsuite - register components
+@snippet samples/testsuite-support/main.cpp testsuite - register components
 
 Add testsuite components to `config.yaml`:
 
@@ -491,6 +491,21 @@ def test_service(service_client):
     ...
 @endcode
 
+@anchor uservice_oneshot
+#### uservice_oneshot testsuite tests
+
+Testsuite allows to create tests that start a new service instance for the test and stop it on test finish:
+
+@snippet samples/testsuite-support/tests/test_metrics.py  uservice_oneshot sample 
+
+Such functionality slows down the tests run, but it may be required
+* to test service state right after the service start,
+* or to test that the service stops fine at some point,
+* or the test breaks the service for some time and restarting it is faster than waiting for recovery.
+
+For per-daemon fixtures see @ref pytest_userver.plugins.service.daemon_scoped_mark "daemon_scoped_mark" fixture.
+
+
 ----------
 
 @htmlonly <div class="bottom-nav"> @endhtmlonly

scripts/docs/en/userver/roadmap_and_changelog.md

@@ -48,7 +48,7 @@ Changelog news also go to the
   to [akhoroshev](https://github.com/akhoroshev) for the PR!
 * Deadline Propagation for PostgreSQL is now enabled by default and can be controlled via `deadline-propagation-enabled`
   static option of the components::Postgres.
-* Testsuite now supports `@pytest.mark.uservice_oneshot`.
+* Testsuite now supports @ref uservice_oneshot "@pytest.mark.uservice_oneshot".
 * utils::regex now always uses a faster and safer Re2 instead of boost::regex.
 * Dynamic config `USERVER_HANDLER_STREAM_API_ENABLED` is not used any more.
 * server::handlers::HttpHandlerStatic now has a `expires` static config option.