add testing section to parser

Author: am29d

docs/utilities/parser.md

@@ -249,3 +249,51 @@ The package `@types/aws-lambda` is a popular project that contains type definiti
 Powertools parser utility also bring AWS Lambda event types based on the built-in schema definitions.
 
 We recommend to use the types provided by the parser utility. If you encounter any issues or have any feedback, please [submit an issue](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose).
+
+## Testing your code
+
+When testing your handler with **parser decorator** you need to use double assetion to bypass TypeScript type checking in your tests.
+This is useful when you want to test the handler for invalid payloads or when you want to test the error handling.
+If you are you use middy middleware, you don't need to do this.
+
+=== "handlerDecorator.test.ts"
+
+    ```typescript hl_lines="29"
+    --8<-- "examples/snippets/parser/unitTestDecorator.ts"
+    ```
+
+    1. Use double assertion `as unknown as X` to bypass TypeScript type checking in your tests
+
+=== "handlerDecorator.ts"
+
+    ```typescript
+    --8<-- "examples/snippets/parser/decorator.ts"
+    ```
+
+=== "schema.ts"
+
+    ```typescript"
+    --8<-- "examples/snippets/parser/schema.ts"
+    ```
+
+This also works when using `safeParse` option.
+
+=== "handlerSafeParse.test.ts"
+
+    ```typescript hl_lines="24-32 38 48"
+    --8<-- "examples/snippets/parser/unitTestSafeParse.ts"
+    ```
+    
+    1. Use double assertion to pass expected types to the handler
+
+=== "handlerSafeParse.ts"
+
+    ```typescript
+    --8<-- "examples/snippets/parser/safeParseDecorator.ts"
+    ```
+
+=== "schema.ts"
+
+    ```typescript"
+    --8<-- "examples/snippets/parser/schema.ts"
+    ```

examples/snippets/parser/safeParseDecorator.ts

@@ -7,6 +7,7 @@ import type {
   EventBridgeEvent,
 } from '@aws-lambda-powertools/parser/types';
 import { Logger } from '@aws-lambda-powertools/logger';
+import { EventBridgeEnvelope } from '@aws-lambda-powertools/parser/envelopes';
 
 const logger = new Logger();
 
@@ -26,7 +27,11 @@ const orderSchema = z.object({
 type Order = z.infer<typeof orderSchema>;
 
 class Lambda implements LambdaInterface {
-  @parser({ schema: orderSchema, safeParse: true }) // (1)!
+  @parser({
+    schema: orderSchema,
+    envelope: EventBridgeEnvelope,
+    safeParse: true,
+  }) // (1)!
   public async handler(
     event: ParsedResult<EventBridgeEvent, Order>,
     _context: Context

examples/snippets/parser/unitTestDecorator.ts

@@ -0,0 +1,34 @@
+import { orderSchema } from 'examples/snippets/parser/schema';
+import { Context } from 'aws-lambda';
+import { handler } from 'examples/snippets/parser/decorator';
+import { z } from 'zod';
+
+describe('Test handler', () => {
+  type Order = z.infer<typeof orderSchema>;
+
+  it('should parse event successfully', async () => {
+    const testEvent = {
+      id: 123,
+      description: 'test',
+      items: [
+        {
+          id: 1,
+          quantity: 1,
+          description: 'item1',
+        },
+      ],
+    };
+
+    await expect(handler(testEvent, {} as Context)).resolves.not.toThrow();
+  });
+
+  it('should throw error if event is invalid', async () => {
+    const testEvent = { foo: 'bar' };
+    await expect(
+      handler(
+        testEvent as unknown as Order, // (1)!
+        {} as Context
+      )
+    ).rejects.toThrow();
+  });
+});

examples/snippets/parser/unitTestSafeParse.ts

@@ -0,0 +1,53 @@
+import { orderSchema } from 'examples/snippets/parser/schema';
+import { Context } from 'aws-lambda';
+import { handler } from 'examples/snippets/parser/safeParseDecorator';
+import { z } from 'zod';
+import {
+  ParsedResult,
+  EventBridgeEvent,
+} from '@aws-lambda-powertools/parser/types';
+
+describe('Test handler', () => {
+  type Order = z.infer<typeof orderSchema>;
+
+  it('should parse event successfully', async () => {
+    const testEvent = {
+      version: '0',
+      id: '6a7e8feb-b491-4cf7-a9f1-bf3703467718',
+      'detail-type': 'OrderPurchased',
+      source: 'OrderService',
+      account: '111122223333',
+      time: '2020-10-22T18:43:48Z',
+      region: 'us-west-1',
+      resources: ['some_additional'],
+      detail: {
+        id: 10876546789,
+        description: 'My order',
+        items: [
+          {
+            id: 1015938732,
+            quantity: 1,
+            description: 'item xpto',
+          },
+        ],
+      },
+    };
+
+    await expect(
+      handler(
+        testEvent as unknown as ParsedResult<EventBridgeEvent, Order>, // (1)!
+        {} as Context
+      )
+    ).resolves.not.toThrow();
+  });
+
+  it('should throw error if event is invalid', async () => {
+    const testEvent = { foo: 'bar' };
+    await expect(
+      handler(
+        testEvent as unknown as ParsedResult<EventBridgeEvent, Order>,
+        {} as Context
+      )
+    ).rejects.toThrow();
+  });
+});