Skip to content

Commit 4e50b80

Browse files
GarrettBeattyGarrettBeatty
authored
Add README (#1971)
1 parent d4d7dc7 commit 4e50b80

File tree

6 files changed

+383
-1
lines changed

6 files changed

+383
-1
lines changed

‎.autover/changes/aeef605f-6fd5-4280-94c7-ddffa1a3d021.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"Projects": [
3+
{
4+
"Name": "Amazon.Lambda.TestTool",
5+
"Type": "Patch",
6+
"ChangelogMessages": [
7+
"Add README"
8+
]
9+
}
10+
]
11+
}

‎Tools/LambdaTestTool-v2/CONTRIBUTING.MD

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Contributing Guidelines
2+
3+
Please follow our main contribution [guide](https://github.com/aws/aws-lambda-dotnet/blob/master/CONTRIBUTING.md) for high level details on how to contribute.
4+
5+
## Lambda Test Tool Specific Contribution Details
6+
7+
### Running the Test Tool Project via an IDE
8+
9+
Download this repository and create/modify the launch settings `Properties/launchSettings.json` to startup the test tool
10+
11+
```json
12+
{
13+
"profiles": {
14+
"Lambda Test Tool": {
15+
"commandName": "Project",
16+
"commandLineArgs": "start --lambda-emulator-port 5050 --api-gateway-emulator-port 5051 --api-gateway-emulator-mode Rest",
17+
"environmentVariables": {
18+
"APIGATEWAY_EMULATOR_ROUTE_CONFIG": {
19+
"LambdaResourceName": "AddLambdaFunction",
20+
"HttpMethod": "Get",
21+
"Path": "/add/{x}/{y}"
22+
}
23+
}
24+
}
25+
}
26+
}
27+
28+
```
29+
30+
Follow the [README](README.md#example-lambda-function-setup) for setting up a local lambda function to pair with the emulator.
31+

‎Tools/LambdaTestTool-v2/README.md

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
# AWS Lambda Test Tool
2+
3+
## Overview
4+
The AWS Lambda Test Tool provides local testing capabilities for .NET Lambda functions with support for both Lambda emulation and API Gateway emulation. This tool allows developers to test their Lambda functions locally in three different modes:
5+
6+
1. Lambda Emulator Mode
7+
2. API Gateway Emulator Mode
8+
3. Combined Mode (both emulators)
9+
10+
![img.png](img.png)
11+
12+
## Comparison with Previous Test Tool
13+
14+
The AWS Lambda Test Tool is an evolution of the previous [AWS .NET Mock Lambda Test Tool](https://github.com/aws/aws-lambda-dotnet/tree/master/Tools/LambdaTestTool), with several key improvements:
15+
16+
### New Features
17+
- **API Gateway Emulation**: Direct support for testing API Gateway integrations locally
18+
- Updated to use a new flow for loading Lambda functions that mimics closer to the Lambda service. This solves many of the issues with the older tool when it came to loading dependencies.
19+
- Ability to have multiple Lambda functions use the same instance of the test tool.
20+
- UI refresh
21+
- [Support for integration with .NET Aspire](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/issues/17)
22+
23+
# AWS Lambda Test Tool
24+
25+
- [Overview](#overview)
26+
- [Comparison with Previous Test Tool](#comparison-with-previous-test-tool)
27+
- [New Features](#new-features)
28+
- [Getting help](#getting-help)
29+
- [.NET Aspire integration](#net-aspire-integration)
30+
- [Installing](#installing)
31+
- [Running the Test Tool](#running-the-test-tool)
32+
- [Lambda Emulator Mode](#lambda-emulator-mode)
33+
- [API Gateway Emulator Mode](#api-gateway-emulator-mode)
34+
- [Required Configuration](#required-configuration)
35+
- [Combined Mode](#combined-mode)
36+
- [Command Line Options](#command-line-options)
37+
- [API Gateway Configuration](#api-gateway-configuration)
38+
- [Single Route Configuration](#single-route-configuration)
39+
- [Multiple Routes Configuration](#multiple-routes-configuration)
40+
- [Example Lambda Function Setup](#example-lambda-function-setup)
41+
- [1. Lambda Function Code](#1-lambda-function-code)
42+
- [Option 1: Using Top-Level Statements](#option-1-using-top-level-statements)
43+
- [Option 2: Using Class Library](#option-2-using-class-library)
44+
- [2. AWS_LAMBDA_RUNTIME_API](#2-aws_lambda_runtime_api)
45+
- [3. API Gateway Configuration](#3-api-gateway-configuration)
46+
- [4. Testing the Function](#4-testing-the-function)
47+
48+
## Getting help
49+
50+
This tool is currently in preview and there are some known limitations. For questions and problems please open a GitHub issue in this repository.
51+
52+
## .NET Aspire integration
53+
The easiest way to get started using the features of the new test tool is with .NET Aspire. The integration takes care of installing the tool and provides .NET Aspire extension methods for configuring your Lambda functions and API Gateway emulator in the .NET Aspire AppHost. It avoids all of the steps list below for installing the tooling and setting up environment variables.
54+
55+
Check out the following tracker issue for information on the .NET Aspire integration and steps for getting started. https://github.com/aws/integrations-on-dotnet-aspire-for-aws/issues/17
56+
57+
## Installing
58+
59+
The tool is distributed as .NET Global Tool. To install the tool execute the following command:
60+
61+
```
62+
dotnet tool install -g amazon.lambda.testtool
63+
```
64+
65+
To update the tool run the following command:
66+
67+
```
68+
dotnet tool update -g amazon.lambda.testtool
69+
```
70+
71+
## Running the Test Tool
72+
73+
### Lambda Emulator Mode
74+
Use this mode when you want to test Lambda functions directly without API Gateway integration.
75+
76+
```
77+
# Start Lambda emulator on port 5050
78+
dotnet lambda-test-tool start --lambda-emulator-port 5050
79+
```
80+
81+
### API Gateway Emulator Mode
82+
Use this mode when you want to test Lambda functions through API Gateway endpoints. **Note: Running this mode by itself will not work, you will still need have the lambda runtime client running elsewhere and reference it in the `Endpoint` parameter in the `APIGATEWAY_EMULATOR_ROUTE_CONFIG` env varible (see below [Required Configuration](#required-configuration))** Api gateway mode requires additional configuration through environment variables.
83+
84+
```
85+
# Start API Gateway emulator on port 5051 in REST mode
86+
dotnet lambda-test-tool start \
87+
--api-gateway-emulator-port 5051 \
88+
--api-gateway-emulator-mode Rest
89+
90+
```
91+
#### Required Configuration
92+
When running via command line, you must set the environment variable for API Gateway route configuration:
93+
94+
Linux/macOS:
95+
```bash
96+
export APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"{LAMBDA_RUNTIME_API}"}'
97+
98+
```
99+
100+
Windows (Command Prompt):
101+
102+
```
103+
set APIGATEWAY_EMULATOR_ROUTE_CONFIG={"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"{LAMBDA_RUNTIME_API}"}
104+
105+
```
106+
107+
Windows (PowerShell):
108+
109+
```
110+
$env:APIGATEWAY_EMULATOR_ROUTE_CONFIG='{"LambdaResourceName":"AddLambdaFunction","HttpMethod":"Get","Path":"/add/{x}/{y}","Endpoint":"{LAMBDA_RUNTIME_API}"}'
111+
112+
```
113+
114+
Replace `{LAMBDA_RUNTIME_API}` with your Lambda runtime API endpoint (e.g., "http://localhost:5050/AddLambdaFunction" or the endpoint specified in your `AWS_LAMBDA_RUNTIME_API` environment variable).
115+
116+
117+
### Combined Mode
118+
Use this mode when you want to run both Lambda and API Gateway emulators simultaneously.
119+
120+
```
121+
# Start both emulators
122+
dotnet lambda-test-tool start \
123+
--lambda-emulator-port 5050 \
124+
--api-gateway-emulator-port 5051 \
125+
--api-gateway-emulator-mode Rest
126+
```
127+
128+
## Command Line Options
129+
| Option | Description | Required For |
130+
|--------|-------------|--------------|
131+
| `--lambda-emulator-port` | Port for Lambda emulator | Lambda Mode |
132+
| `--lambda-emulator-host` | Host for Lambda emulator | Lambda Mode |
133+
| `--api-gateway-emulator-port` | Port for API Gateway | API Gateway Mode |
134+
| `--api-gateway-emulator-mode` | API Gateway mode (Rest/HttpV1/HttpV2) | API Gateway Mode |
135+
| `--no-launch-window` | Disable auto-launching web interface | Optional |
136+
137+
138+
## API Gateway Configuration
139+
When using API Gateway mode, you need to configure the route mapping using the APIGATEWAY_EMULATOR_ROUTE_CONFIG environment variable. This can be a single route or an array of routes:
140+
141+
### Single Route Configuration
142+
```
143+
{
144+
"LambdaResourceName": "AddLambdaFunction",
145+
"HttpMethod": "Get",
146+
"Path": "/add/{x}/{y}"
147+
}
148+
```
149+
150+
### Multiple Routes Configuration
151+
152+
```
153+
[
154+
{
155+
"LambdaResourceName": "AddLambdaFunction",
156+
"HttpMethod": "Get",
157+
"Path": "/add/{x}/{y}"
158+
},
159+
{
160+
"LambdaResourceName": "SubtractLambdaFunction",
161+
"HttpMethod": "Get",
162+
"Path": "/minus/{x}/{y}"
163+
}
164+
]
165+
166+
```
167+
168+
169+
#### Wildcard Paths
170+
The API Gateway emulator supports the use of wildcard path. To define a wildcard path, you can use the `{proxy+}` syntax in the route pattern. See [here](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html) for a more detailed explanation on how proxies work.
171+
172+
Here's an example of how to set up an API Gateway emulator with a wildcard path:
173+
174+
```
175+
[
176+
{
177+
"LambdaResourceName": "RootFunction",
178+
"HttpMethod": "Get",
179+
"Path": "/root"
180+
},
181+
{
182+
"LambdaResourceName": "MyOtherLambdaFunction",
183+
"HttpMethod": "Get",
184+
"Path": "/root/{proxy+}"
185+
}
186+
]
187+
188+
```
189+
190+
This JSON configuration sets up two API Gateway resources:
191+
192+
1. `/root` that is mapped to the `RootFunction` Lambda function.
193+
2. `/root/{proxy+}` that is a proxy resource mapped to the `MyOtherLambdaFunction` Lambda function.
194+
195+
The `{proxy+}` syntax in the second path allows the API Gateway to proxy any additional path segments to the integrated Lambda function.
196+
197+
## Example Lambda Function Setup
198+
199+
Here's a simple Lambda function that adds two numbers together.
200+
201+
### 1. Lambda Function Code
202+
This can be implemented in two ways:
203+
204+
#### Option 1: Using Top-Level Statements
205+
206+
207+
```csharp
208+
using Amazon.Lambda.APIGatewayEvents;
209+
using Amazon.Lambda.Core;
210+
using Amazon.Lambda.RuntimeSupport;
211+
using Amazon.Lambda.Serialization.SystemTextJson;
212+
213+
var Add = (APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context) =>
214+
{
215+
// Parse x and y from the path parameters
216+
var x = int.Parse(request.PathParameters["x"]);
217+
var y = int.Parse(request.PathParameters["y"]);
218+
return (x + y).ToString();
219+
};
220+
221+
await LambdaBootstrapBuilder.Create(Add, new CamelCaseLambdaJsonSerializer())
222+
.Build()
223+
.RunAsync();
224+
225+
```
226+
227+
Configure the Lambda function to use the test tool:
228+
229+
**Properties/launchSettings.json**
230+
```
231+
{
232+
"profiles": {
233+
"AspireTestFunction": {
234+
"commandName": "Project",
235+
"environmentVariables": {
236+
"AWS_LAMBDA_RUNTIME_API": "localhost:5050/AddLambdaFunction"
237+
}
238+
}
239+
}
240+
}
241+
```
242+
243+
#### Option 2: Using Class Library
244+
```
245+
using Amazon.Lambda.APIGatewayEvents;
246+
using Amazon.Lambda.Core;
247+
248+
namespace MyLambdaFunction;
249+
250+
public class Function
251+
{
252+
public int Add(APIGatewayHttpApiV2ProxyRequest request, ILambdaContext context)
253+
{
254+
var x = int.Parse(request.PathParameters["x"]);
255+
var y = int.Parse(request.PathParameters["y"]);
256+
return x + y;
257+
}
258+
}
259+
```
260+
261+
Configure the Lambda function to use the test tool:
262+
263+
**Properties/launchSettings.json**
264+
```
265+
{
266+
"profiles": {
267+
"LambdaRuntimeClient_FunctionHandler": {
268+
"workingDirectory": ".\\bin\\$(Configuration)\\net8.0",
269+
"commandName": "Executable",
270+
"commandLineArgs": "exec --depsfile ./MyLambdaFunction.deps.json --runtimeconfig ./MyLambdaFunction.runtimeconfig.json %USERPROFILE%/.dotnet/tools/.store/amazon.lambda.testtool/{TEST_TOOL_VERSION}/amazon.lambda.testtool/{TEST_TOOL_VERSION}/content/Amazon.Lambda.RuntimeSupport/{TARGET_FRAMEWORK}/Amazon.Lambda.RuntimeSupport.dll MyLambdaFunction::MyLambdaFunction.Function::Add",
271+
"executablePath": "dotnet",
272+
"environmentVariables": {
273+
"AWS_LAMBDA_RUNTIME_API": "localhost:5050/AddLambdaFunction"
274+
}
275+
}
276+
}
277+
}
278+
```
279+
280+
There are three variables you may need to replace:
281+
282+
There are three variables you need to update in the launch settings:
283+
284+
1. `{TEST_TOOL_VERSION}` - Replace with the current Amazon.Lambda.TestTool version (e.g., `0.0.3` in the example above)
285+
- This appears in the path: `.store/amazon.lambda.testtool/{TEST_TOOL_VERSION}/amazon.lambda.testtool/{TEST_TOOL_VERSION}/content/`
286+
287+
2. `{TARGET_FRAMEWORK}` - Replace with your Lambda project's target framework version (e.g., `net8.0` in the example above)
288+
- This appears in two places:
289+
- The working directory: `.\\bin\\$(Configuration)\\{TARGET_FRAMEWORK}`
290+
- The runtime support DLL path: `Amazon.Lambda.RuntimeSupport/{TARGET_FRAMEWORK}/Amazon.Lambda.RuntimeSupport.dll`
291+
292+
3. `{FUNCTION_HANDLER}` - Replace with your function's handler using the format: `<project_name>::<namespace>.<class>::<method_name>`
293+
- Example: `MyLambdaFunction::MyLambdaFunction.Function::Add`
294+
295+
296+
297+
### 2. AWS_LAMBDA_RUNTIME_API
298+
299+
The `AWS_LAMBDA_RUNTIME_API` environment variable tells the Lambda function where to find the Lambda runtime API endpoint. It has the following format:
300+
301+
`host:port/functionName`
302+
303+
304+
The host and port should match the port that the lambda emulator is running on.
305+
In this example we will be running the lambda runtime api emulator on `localhost` on port `5050` and our function name will be `AddLambdaFunction`. **Warning**: You should *not* add `http://` prefix to the host (if you do the lambda will fail to connect).
306+
307+
### 3. API Gateway Configuration
308+
To expose this Lambda function through API Gateway, set the APIGATEWAY_EMULATOR_ROUTE_CONFIG:
309+
310+
```
311+
{
312+
"LambdaResourceName": "AddLambdaFunction",
313+
"HttpMethod": "GET",
314+
"Path": "/add/{x}/{y}"
315+
}
316+
```
317+
318+
### 4. Testing the Function
319+
1. Start the test tool with both Lambda and API Gateway emulators:
320+
```
321+
dotnet lambda-test-tool start \
322+
--lambda-emulator-port 5050 \
323+
--api-gateway-emulator-port 5051 \
324+
--api-gateway-emulator-mode HTTPV2
325+
326+
```
327+
2. Send a test request:
328+
```
329+
curl -X GET "http://localhost:5051/add/5/3" -H "Content-Type: application/json" -d '"hello world"'
330+
```
331+
332+
Expected response:
333+
```
334+
8
335+
```

‎Tools/LambdaTestTool-v2/Resources/img.png

68.2 KB
Loading

‎Tools/LambdaTestTool-v2/src/Amazon.Lambda.TestTool/Amazon.Lambda.TestTool.csproj

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
<Version>0.0.3</Version>
1919
<NoWarn>NU5100</NoWarn>
2020
<RollForward>Major</RollForward>
21+
<PackageReadmeFile>README.md</PackageReadmeFile>
2122
</PropertyGroup>
2223

2324
<ItemGroup Condition="$(Configuration) == 'Release'">
@@ -69,4 +70,8 @@
6970
</None>
7071
</ItemGroup>
7172

73+
74+
<ItemGroup>
75+
<None Include="../../README.md" Pack="true" PackagePath="\" />
76+
</ItemGroup>
7277
</Project>

0 commit comments

Comments
 (0)