add doc readme

Author: sebsto

readme.md

@@ -294,6 +294,49 @@ try await runtime.run()
 
 You can learn how to deploy and invoke this function in [the background tasks example README file](Examples/BackgroundTasks/README.md).
 
+## Testing Locally
+
+Before deploying your code to AWS Lambda, you can test it locally by running the executable target on your local machine. It will look like this on CLI:
+
+```sh
+swift run
+```
+
+When not running inside a Lambda execution environment, it starts a local HTTP server listening on port 7000. You can invoke your local Lambda function by sending an HTTP POST request to `http://127.0.0.1:7000/invoke`.
+
+The request must include the JSON payload expected as an `event` by your function. You can create a text file with the JSON payload documented by AWS or captured from a trace.  In this example, we used [the APIGatewayv2 JSON payload from the documentation](https://docs.aws.amazon.com/lambda/latest/dg/services-apigateway.html#apigateway-example-event), saved as `events/create-session.json` text file.
+
+Then we use curl to invoke the local endpoint with the test JSON payload.
+
+```sh
+curl -v --header "Content-Type:\ application/json" --data @events/create-session.json http://127.0.0.1:7000/invoke
+*   Trying 127.0.0.1:7000...
+* Connected to 127.0.0.1 (127.0.0.1) port 7000
+> POST /invoke HTTP/1.1
+> Host: 127.0.0.1:7000
+> User-Agent: curl/8.4.0
+> Accept: */*
+> Content-Type:\ application/json
+> Content-Length: 1160
+> 
+< HTTP/1.1 200 OK
+< content-length: 247
+< 
+* Connection #0 to host 127.0.0.1 left intact
+{"statusCode":200,"isBase64Encoded":false,"body":"...","headers":{"Access-Control-Allow-Origin":"*","Content-Type":"application\/json; charset=utf-8","Access-Control-Allow-Headers":"*"}}
+```
+### Modifying the local endpoint
+
+By default, when using the local Lambda server, it listens on the `/invoke` endpoint.
+
+Some testing tools, such as the [AWS Lambda runtime interface emulator](https://docs.aws.amazon.com/lambda/latest/dg/images-test.html), require a different endpoint. In that case, you can use the `LOCAL_LAMBDA_SERVER_INVOCATION_ENDPOINT` environment variable to force the runtime to listen on a different endpoint.
+
+Example:
+
+```sh
+LOCAL_LAMBDA_SERVER_INVOCATION_ENDPOINT=/2015-03-31/functions/function/invocations swift run
+```
+
 ## Deploying your Swift Lambda functions