docs(maintenance): fix install instructions & switch test runner (aws-powertools#3030)

Author: dreamorosi

examples/app/README.md

@@ -2,54 +2,61 @@
 
 This is a deployable CDK app that deploys AWS Lambda functions as part of a CloudFormation stack. These Lambda functions use the utilities made available as part of Powertools for AWS Lambda (TypeScript) to demonstrate their usage.
 
-> **Note**
-> You will need to have a valid AWS Account in order to deploy these resources. These resources may incur costs to your AWS Account. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+> [!Warning]
+> You will need to have a valid AWS Account in order to deploy these resources. Many of the services in the example are covered [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but you may incur charges if you exceed the free tier limits.
+If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
 
 The example functions, located in the `functions` folder, are frontend by a REST API that is deployed using AWS API Gateway.
 
 The API has three endpoints:
 
- * `POST /` - Adds an item to the DynamoDB table
- * `GET /` - Retrieves all items from the DynamoDB table
- * `GET /{id}` - Retrieves a specific item from the DynamoDB table
+* `POST /` - Adds an item to the DynamoDB table
+* `GET /` - Retrieves all items from the DynamoDB table
+* `GET /{id}` - Retrieves a specific item from the DynamoDB table
 
 ## Deploying the stack
 
- * Navigate to this location of the repo in your terminal (`examples/cdk`)
- * `npm ci`
- * `npm run cdk deploy --all --profile <YOUR_AWS_PROFILE>`
+> [!Note]
+> The `examples/app` directory where this example is located is part of a monorepo. If you are interested in deploying the example only, follow the instructions below.
+> If instead you are working on the monorepo and want to deploy the example, follow the instructions in the [CONTRIBUTING](../../CONTRIBUTING.md#dev-setup) doc, then run `npm run cdk deploy -w examples/app` from the project's root.
 
-Note: Prior to deploying you may need to run `cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` if you have not already bootstrapped your account for CDK.
+If this is the first time you're using CDK in your AWS Account & AWS Region, you may need to run `npm run cdk bootstrap aws://<YOU_AWS_ACCOUNT_ID>/<AWS_REGION> --profile <YOUR_AWS_PROFILE>` to bootstrap your account for CDK.
 
-> **Note**
-> You can find your API Gateway Endpoint URL in the output values displayed after deployment.
+Then, still from within the `examples/app` directory, run the following commands:
+
+* `npm i --prefix ./` to install the dependencies
+* `npm run cdk deploy` and follow the prompts to deploy the stack
+
+When the deployment is complete, you will see the output values that include the API Gateway Endpoint URL.
 
 ## Execute the functions via API Gateway
 
 Use the API Gateway Endpoint URL from the output values to execute the functions. First, let's add two items to the DynamoDB Table by running:
 
 ```bash
-curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myfirstitem","name":"Some Name for the first item"}' https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
-curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myseconditem","name":"Some Name for the second item"}' https://randomid1245.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myfirstitem","name":"Some Name for the first item"}' https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XPOST --header 'Content-Type: application/json' --data '{"id":"myseconditem","name":"Some Name for the second item"}' https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
 ````
 
 Now, let's retrieve all items by running:
 
 ```sh
-curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/
+curl -XGET https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/
 ```
 
 And finally, let's retrieve a specific item by running:
+
 ```bash
-curl -XGET https://randomid12345.execute-api.eu-central-1.amazonaws.com/prod/myseconditem/
+curl -XGET https://<api-id>.execute-api.eu-central-1.amazonaws.com/prod/myseconditem/
 ```
 
 ## Observe the outputs in AWS CloudWatch & X-Ray
 
 ### CloudWatch
 
 If we check the logs in CloudWatch, we can see that the logs are structured like this
-```
+
+```text
 2022-04-26T17:00:23.808Z	e8a51294-6c6a-414c-9777-6b0f24d8739b	DEBUG	
 {
     "level": "DEBUG",
@@ -62,10 +69,11 @@ If we check the logs in CloudWatch, we can see that the logs are structured like
 
 By having structured logs like this, we can easily search and analyse them in [CloudWatch Logs Insight](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). Run the following query to get all messages for a specific `awsRequestId`:
 
-````
+````text
 filter awsRequestId="bcd50969-3a55-49b6-a997-91798b3f133a"
  | fields timestamp, message
 ````
+
 ### AWS X-Ray
 
 As we have enabled tracing for our Lambda-Funtions, you can visit [AWS CloudWatch Console](https://console.aws.amazon.com/cloudwatch/) and see [Traces](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-traces) and a [Service Map](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-using-xray-maps.html) for our application.
@@ -76,4 +84,4 @@ To delete the sample application that you created, run the command below while i
 
 ```bash
 cdk destroy
-```
+```

examples/app/cdk/example-stack.ts

@@ -1,3 +1,5 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
 import { LambdaIntegration, RestApi } from 'aws-cdk-lib/aws-apigateway';
 import {
@@ -21,6 +23,12 @@ import { StringParameter } from 'aws-cdk-lib/aws-ssm';
 import type { Construct } from 'constructs';
 import { FunctionWithLogGroup } from './function-with-logstream-construct.js';
 
+// Get the current file URL
+const __filename = fileURLToPath(import.meta.url);
+
+// Get the current directory
+const __dirname = dirname(__filename);
+
 export class PowertoolsExampleStack extends Stack {
   public constructor(scope: Construct, id: string, props?: StackProps) {
     super(scope, id, props);
@@ -80,7 +88,7 @@ export class PowertoolsExampleStack extends Stack {
      * Because we are using ESM and tree shake, we create an optimized bundle.
      */
     const putItemFn = new FunctionWithLogGroup(this, 'put-item-fn', {
-      entry: './functions/put-item.ts',
+      entry: join(__dirname, '..', './functions/put-item.ts'),
       functionName: 'powertools-example-put-item',
       bundling: {
         minify: true,
@@ -124,7 +132,7 @@ export class PowertoolsExampleStack extends Stack {
      * in a centralized way across all your functions.
      */
     const getAllItemsFn = new FunctionWithLogGroup(this, 'get-all-items-fn', {
-      entry: './functions/get-all-items.ts',
+      entry: join(__dirname, '..', './functions/get-all-items.ts'),
       functionName: 'powertools-example-get-all-items',
       layers: [powertoolsLayer], // we use the powertools layer
       bundling: {
@@ -150,7 +158,7 @@ export class PowertoolsExampleStack extends Stack {
      * dependencies in it.
      */
     const getByIdFn = new FunctionWithLogGroup(this, 'get-by-id-fn', {
-      entry: './functions/get-by-id.ts',
+      entry: join(__dirname, '..', './functions/get-by-id.ts'),
       functionName: 'powertools-example-get-by-id',
       bundling: {
         minify: true,
@@ -172,7 +180,7 @@ export class PowertoolsExampleStack extends Stack {
       this,
       'process-items-stream-fn',
       {
-        entry: './functions/process-items-stream.ts',
+        entry: join(__dirname, '..', './functions/process-items-stream.ts'),
         functionName: 'powertools-example-process-items-stream',
         layers: [powertoolsLayer],
         bundling: {

examples/app/jest.config.cjs

@@ -13,7 +13,7 @@
     "test": "npm run test:unit",
     "lint": "biome lint .",
     "lint:fix": "biome check --write .",
-    "test:unit": "export POWERTOOLS_DEV=true && jest --silent",
+    "test:unit": "export POWERTOOLS_DEV=true && vitest --run --silent",
     "test:e2e": "echo 'To be implemented ...'",
     "cdk": "cdk"
   },
@@ -29,16 +29,14 @@
   },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.145",
-    "@types/jest": "^29.5.12",
     "@types/node": "22.5.2",
     "aws-cdk": "^2.155.0",
     "aws-cdk-lib": "^2.155.0",
     "constructs": "^10.3.0",
-    "jest": "^29.7.0",
     "source-map-support": "^0.5.21",
-    "ts-jest": "^29.2.5",
     "tsx": "^4.19.0",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
   },
   "dependencies": {
     "@aws-lambda-powertools/batch": "^2.7.0",
@@ -51,13 +49,9 @@
     "@aws-sdk/lib-dynamodb": "^3.637.0",
     "@middy/core": "^4.7.0",
     "@types/aws-lambda": "^8.10.145",
-    "@types/jest": "^29.5.12",
     "@types/node": "22.5.2",
     "constructs": "^10.3.0",
     "esbuild": "^0.23.1",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
   }
 }

examples/app/package.json

@@ -1,9 +1,13 @@
 import { App } from 'aws-cdk-lib';
 import { Template } from 'aws-cdk-lib/assertions';
+import { describe, it } from 'vitest';
 import { PowertoolsExampleStack } from '../cdk/example-stack.js';
 
-test('CDK code synthesize', () => {
+describe('CDK example stack', () => {
   const app = new App();
   const stack = new PowertoolsExampleStack(app, 'MyTestStack');
-  Template.fromStack(stack).resourceCountIs('AWS::Lambda::Function', 4);
+
+  it('has 4 Lambda functions', () => {
+    Template.fromStack(stack).resourceCountIs('AWS::Lambda::Function', 4);
+  });
 });

examples/app/tests/cdk-app.test.ts

@@ -0,0 +1,7 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+  },
+});