docs(all): clarifications & fixes

docs/core/logger.md

@@ -105,11 +105,15 @@ Key | Example
 **function_arn**: `string` | `arn:aws:lambda:eu-central-1:123456789012:function:shopping-cart-api-lambda-prod-eu-central-1`
 **function_request_id**: `string` | `c6af9ac6-7b61-11e6-9a41-93e812345678`
 
-#### Method 1, using a [Middy](https://github.com/middyjs/middy) middleware:
+=== "Middleware"
 
-=== "handler.ts"
+    !!! note
+        Middy comes bundled with Logger, so you can just import it when using the middleware.
+
+    !!! tip "Using Middy for the first time?"
+        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
 
-    ```typescript hl_lines="1 9-11"
+    ```typescript hl_lines="1-2 10-11"
     import { Logger, injectLambdaContext } from "@aws-lambda-powertools/logger";
     import middy from '@middy/core';
 
@@ -123,9 +127,7 @@ Key | Example
         .use(injectLambdaContext(logger));
     ```
 
-#### Method 2, calling the `addContext` method:
-
-=== "handler.ts"
+=== "Manual"
 
     ```typescript hl_lines="7"
     import { Logger } from "@aws-lambda-powertools/logger";
@@ -141,9 +143,7 @@ Key | Example
     };
     ```
 
-#### Method 3, using a class decorator:
-
-=== "handler.ts"
+=== "Decorator"
 
     ```typescript hl_lines="7"
     import { Logger } from "@aws-lambda-powertools/logger";
@@ -621,4 +621,47 @@ This is how the printed log would look:
             },
             "awsAccountId": "123456789012"
         }
-    ```
+    ```
+
+## Testing your code
+
+### Inject Lambda Context
+
+When unit testing your code that makes use of `logger.addContext()` or `injectLambdaContext` middleware and decorator, you can optionally pass a dummy Lambda Context if you want your logs to contain this information.
+
+This is a Jest sample that provides the minimum information necessary for Logger to inject context data:
+
+=== "handler.test.ts"
+
+```typescript
+
+const dummyContext = {
+    callbackWaitsForEmptyEventLoop: true,
+    functionVersion: '$LATEST',
+    functionName: 'foo-bar-function',
+    memoryLimitInMB: '128',
+    logGroupName: '/aws/lambda/foo-bar-function',
+    logStreamName: '2021/03/09/[$LATEST]abcdef123456abcdef123456abcdef123456',
+    invokedFunctionArn: 'arn:aws:lambda:eu-central-1:123456789012:function:foo-bar-function',
+    awsRequestId: 'c6af9ac6-7b61-11e6-9a41-93e812345678',
+    getRemainingTimeInMillis: () => 1234,
+    done: () => console.log('Done!'),
+    fail: () => console.log('Failed!'),
+    succeed: () => console.log('Succeeded!'),
+};
+
+describe('MyUnitTest', () => {
+
+    test('Lambda invoked successfully', async () => {
+
+       const testEvent = { test: 'test' };
+        await handler(testEvent, dummyContext);
+
+    });
+
+});
+
+```
+
+!!! tip
+    If you don't want to declare your own dummy Lambda Context, you can use [`ContextExamples.helloworldContext`](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/packages/commons/src/tests/resources/contexts/hello-world.ts#L3-L16) from [`@aws-lambda-powertools/commons`](https://www.npmjs.com/package/@aws-lambda-powertools/commons).

docs/core/metrics.md

@@ -163,6 +163,12 @@ See examples below:
 
 === "Middy middleware"
 
+    !!! note
+        Middy comes bundled with Metrics, so you can just import it when using the middleware.
+
+    !!! tip "Using Middy for the first time?"
+        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
+
     ```typescript hl_lines="5"
     import { Metrics, MetricUnits, logMetrics } from '@aws-lambda-powertools/metrics';
     import { Context } from 'aws-lambda';

docs/core/tracer.md

@@ -72,6 +72,12 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Middleware"
 
+    !!! note
+        Middy comes bundled with Tracer, so you can just import it when using the middleware.
+
+    !!! tip "Using Middy for the first time?"
+        Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
+
     ```typescript hl_lines="1-2 4 7 9"
     import { Tracer } from '@aws-lambda-powertools/tracer';
     import middy from '@middy/core';
@@ -105,7 +111,7 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Manual"
 
-    ```typescript hl_lines="1 3 7 9 11 17 20 24"
+    ```typescript hl_lines="1 3 7 9-10 13-14 20 23 27 29"
     import { Tracer } from '@aws-lambda-powertools/tracer';
 
     const tracer = Tracer(); // Sets service via env var
@@ -252,8 +258,6 @@ You can trace other methods using the `captureMethod` decorator or manual instru
     }
     ```
 
-## Advanced
-
 ### Patching AWS SDK clients
 
 Tracer can patch [AWS SDK clients](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html) and create traces when your application makes calls to AWS services.
@@ -300,6 +304,8 @@ If you're looking to shave a few microseconds, or milliseconds depending on your
     const s3 = tracer.captureAWSClient(new S3({ apiVersion: "2006-03-01" }));
     ```
 
+## Advanced
+
 ### Disabling response auto-capture
 
 Use **`POWERTOOLS_TRACER_CAPTURE_RESPONSE=false`** environment variable to instruct Tracer **not** to serialize function responses as metadata.

docs/index.md

@@ -78,5 +78,5 @@ Each TypeScript utility is installed as standalone NPM package.
 
 ## Connect
 
-* **AWS Developers Slack**: `#lambda-powertools`** - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw){target="_blank"}**
+* **AWS Developers Slack**: `#lambda-powertools` - [Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw){target="_blank"}
 * **Email**: [email protected]

docs/stylesheets/extra.css

@@ -1,40 +1,36 @@
 .md-grid {
-    max-width: 81vw
-}
-
-.highlight .hll {
-    background-color: lavender
-
-    [data-md-color-scheme="slate"] {
-        background-color: rgb(69, 48, 164)
-    }
+    max-width: 81vw;
 }
 
 .md-typeset table:not([class]) {
-    font-size: 0.75rem
+    font-size: 0.75rem;
 }
 
 .md-typeset a {
-    border-bottom: 0.1px dashed black
+    border-bottom: 0.1px dashed black;
 }
 
 .md-typeset table:not([class]) {
-    font-size: 0.75rem
+    font-size: 0.75rem;
 }
 
 .md-nav__link--active {
-    font-weight: bold
+    font-weight: bold;
 }
 
 .md-typeset .admonition, .md-typeset details {
-    font-size: 0.70rem
+    font-size: 0.70rem;
 }
 
 [data-md-color-scheme="slate"] {
-    --md-typeset-a-color: rgb(28, 152, 152)
+    --md-typeset-a-color: rgb(28, 152, 152);
 }
 
 .copyMe {
 	cursor: pointer;
 	border-bottom: 0.1px dashed black;
 }
+
+p code {
+    font-weight: bolder;
+}