Add Testing your code section to docs.

Author: phipag

docs/core/metrics.md

@@ -535,3 +535,97 @@ The following example shows how to configure a custom `MetricsLogger` using the
         }
     }
     ```
+
+## Testing your code
+
+### Suppressing metrics output
+
+If you would like to suppress metrics output during your unit tests, you can use the `POWERTOOLS_DISABLE_METRICS` environment variable. For example, using Maven you can set in your build plugins:
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-surefire-plugin</artifactId>
+    <configuration>
+        <environmentVariables>
+            <POWERTOOLS_DISABLE_METRICS>true</POWERTOOLS_DISABLE_METRICS>
+        </environmentVariables>
+    </configuration>
+</plugin>
+```
+
+### Asserting EMF output
+
+When unit testing your code, you can run assertions against the output generated by the `MetricsLogger`. For the `EmfMetricsLogger`, you can assert the generated JSON blob following the [CloudWatch EMF specification](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) against your expected output.
+
+Consider the following example where we redirect the standard output to a custom `PrintStream`. We use the Jackson library to parse the EMF output into a `JsonNode` and run assertions against that.
+
+```java hl_lines="23 28 33 50-55"
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import com.amazonaws.services.lambda.runtime.Context;
+import com.amazonaws.services.lambda.runtime.RequestHandler;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import software.amazon.lambda.powertools.metrics.model.MetricUnit;
+import software.amazon.lambda.powertools.metrics.testutils.TestContext;
+
+class MetricsTestExample {
+
+    private final PrintStream standardOut = System.out;
+    private final ByteArrayOutputStream outputStreamCaptor = new ByteArrayOutputStream();
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @BeforeEach
+    void setUp() {
+        System.setOut(new PrintStream(outputStreamCaptor));
+    }
+
+    @AfterEach
+    void tearDown() {
+        System.setOut(standardOut);
+    }
+
+    @Test
+    void shouldCaptureMetricsFromAnnotatedHandler() throws Exception {
+        // Given
+        RequestHandler<Map<String, Object>, String> handler = new HandlerWithMetricsAnnotation();
+        Context context = new TestContext();
+        Map<String, Object> input = new HashMap<>();
+
+        // When
+        handler.handleRequest(input, context);
+
+        // Then
+        String emfOutput = outputStreamCaptor.toString().trim();
+        JsonNode rootNode = objectMapper.readTree(emfOutput);
+
+        assertThat(rootNode.has("test-metric")).isTrue();
+        assertThat(rootNode.get("test-metric").asDouble()).isEqualTo(100.0);
+        assertThat(rootNode.get("_aws").get("CloudWatchMetrics").get(0).get("Namespace").asText())
+                .isEqualTo("CustomNamespace");
+        assertThat(rootNode.has("Service")).isTrue();
+        assertThat(rootNode.get("Service").asText()).isEqualTo("CustomService");
+    }
+
+    static class HandlerWithMetricsAnnotation implements RequestHandler<Map<String, Object>, String> {
+        @Override
+        @Metrics(namespace = "CustomNamespace", service = "CustomService")
+        public String handleRequest(Map<String, Object> input, Context context) {
+            MetricsLogger metricsLogger = MetricsLoggerFactory.getMetricsLogger();
+            metricsLogger.addMetric("test-metric", 100, MetricUnit.COUNT);
+            return "OK";
+        }
+    }
+}
+```