\n\n# Serverless plugin test helper\n\n1. [Overview](#overview)\n1. [Installation and setup](#installation-and-setup)\n1. [E2E testing support setup & configuration](#e2e-testing-support-setup--configuration)\n1. [AWS event mocks](#aws-event-mocks)\n1. [Examples](#examples)\n1. [An opinionated approach to serverless testing](#an-opinionated-approach-to-serverless-testing)\n\n_Feedback is appreciated! If you have an idea for how this plugin/library can be improved (or even just a complaint/criticism) then please [open an issue](https://github.com/manwaring/serverless-plugin-test-helper/issues/new)._\n\n# Overview\n\nRunning tests on deployed services (vs locally mocked ones) is an important final step in a robust serverless deployment pipeline because it isn't possible to recreate all aspects of a final solution locally - concerns such as fine-grained resource access through IAM and scalability/performance characteristics of the system can only be assessed while the application is running on AWS. Running these tests on stage/branch-specific versions of the application (see [serverless testing best practices below](#serverless-testing-best-practices)) is difficult to do given the dynamic nature of AWS resource naming. This library makes it easier to write post-deployment tests for applications and services written and deployed using the [Serverless Framework](https://serverless.com/framework/) by locally persisting dynamic AWS resource information such as endpoint URLs and exposing them to your tests via easily-imported helper functions.\n\nBecause unit tests with mocked AWS services are still an important part of a well-tested service (especially for fast developer feedback), this library also includes helper functions to simplify the creation of mock events for the various AWS Lambda integrations.\n\n# Installation and setup\n\nInstall and save the library to `package.json` as a dev dependency:\n\n`npm i --save-dev serverless-plugin-test-helper`\n\n`yarn add serverless-plugin-test-helper -D`\n\n# E2E testing support setup & configuration\n\nTwo parts of this library work together to support E2E testing of your deployed serverless apps:\n\n1. A [Serverless Framework plugin](https://github.com/serverless/plugins) which extends `sls deploy` to save a copy of the generated CloudFormation Stack Output locally - this will persist the dynamically-generated API Gateway endpoint, for example.\n1. A standard Node.js library which can be imported to access local stack output values in tests (or any other code you want to run post-deployment) - this will allow you to access the dynamically-generated API Gateway endpoint that the plugin saved.\n\nTo setup the plugin add the library to the `serverless.yml` `plugins` section:\n\n```yml\nplugins:\n - serverless-plugin-test-helper\n```\n\nBy default the plugin will generate a file containing stack outputs at `.serverless/stack-output/outputs.yml`, which is where the library pulls values from. You can optionally specify an additional path for storing outputs by using the optional `serverless.yml` `custom` section with the `testHelper` key:\n\n```yml\ncustom:\n testHelper: # The 'testHelper' key is used by the plugin to pull in the optional path value\n path: optional/path/for/another/outputs[ .yml | .yaml | .json ]\n```\n\n### Using the library to retrieve stack outputs\n\nImport the helper functions into your test files to retrieve values from deployed stack output:\n\n```ts\nimport { getApiGatewayUrl, getDeploymentBucket, getOutput } from 'serverless-plugin-test-helper';\n\nconst URL = getApiGatewayUrl();\nconst BUCKET_NAME = getDeploymentBucket();\nconst DOCUMENT_STORAGE_BUCKET_NAME = getOutput('DocumentStorageBucket');\n```\n\n- `getApiGatewayUrl()` returns the url of the deployed API Gateway service (if using `http` or `httpApi` as an event type in `serverless.yml`)\n- `getDeploymentBucket()` returns the name of the bucket Serverless Framework generates for uploading CloudFormation templates and zipped source code files as part of the `sls deploy` process\n- `getOutput('output-key-from-stack-outputs')` returns the value of the Cloudformation stack output with the specified key\n\nTo see what output values are available for reference you can check the generated `.serverless/stack-output/outputs.yml` file after a deployment. To make additional values available you can specify up to 60 CloudFormation Stack Outputs in `serverless.yml` using the resources > Outputs section:\n\n```yml\nresources:\n Outputs:\n # Generic example\n Output1: # This is the key that will be used in the generated outputs file\n Description: This is an optional description that will show up in the CloudFormation dashboard\n Value: { Ref: CloudFormationParameterOrResourceYouWishToExport }\n\n # Example referencing a custom S3 bucket used for file storage (defined under Resources section below)\n DocumentStorageBucket: # This is the key that will be used in the generated outputs file\n Description: Name of the S3 bucket used for document storage by this stack\n Value: { Ref: DocumentStorageBucket }\n\n Resources:\n DocumentStorageBucket:\n Type: AWS::S3::Bucket\n```\n\nSee the [AWS CloudFormation documentation on outputs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) for more information on stack outputs.\n\n# AWS event mocks\n\nImport the helper functions and static objects into your test files to generate AWS event and method signature mocks with optional value overrides. Note that this portion of the library can be used without using the E2E testing module.\n\n```ts\nimport {\n ApiGatewayEvent,\n ApiGatewayTokenAuthorizerEvent,\n DynamoDBStreamEvent,\n HttpApiEvent,\n SnsEvent,\n context\n} from 'serverless-plugin-test-helper';\nimport { handler } from './lambda-being-tested';\n\n// Setup events with optional value overrides\nconst event = new ApiGatewayEvent({ body: 'overridden body value' });\nconst event2 = new ApiGatewayTokenAuthorizerEvent();\nconst event3 = new DynamoDBStreamEvent();\nconst event4 = new HttpApiEvent();\nconst event5 = new SnsEvent();\n\n...\n\n// Invoke the handler functions with events\nconst result = await handler(event, context);\nconst result2 = await handler(event2, context);\n\n// TODO write your tests on the results\n\n```\n\n# Examples\n\nThere is [one working example](examples) of how this library can be used in a simple 'hello world' serverless application:\n\n1. [Plugin and event mocks in a TypeScript project with E2E and unit tests](examples/custom-ts)\n\n# Serverless testing best practices\n\nDue to tight coupling with managed services and the difficulty in mocking those same services locally, end-to-end testing is incredibly important for deploying and running serverless applications with confidence. I believe that a good serverless deployment pipeline setup should include the following steps, in order:\n\n## For checkins/merges to default branch\\*\n\n1. Install project and dependencies\n1. Run unit tests\n1. Deploy to a static, non-production environment like staging (using `--stage staging` option in Serverless Framework)†\n1. Run e2e tests in the static, non-production environment†\n1. Optional: include a manual approval step if you want to gate production deploys\n1. Deploy to production environment (with `--stage production`)\n1. Run e2e tests in production\n\n† Repeat steps 3 and 4 for however many static, non-production environments you have (development, staging, demo, etc.)\n\n## For checkins/merges to a feature branch\\*\n\n1. Install project and dependencies\n1. Run unit tests\n1. Deploy to a dynamic, non-production environment (with `--stage ` option in Serverless Framework)\n1. Run e2e tests in the dynamic, non-production environment\n1. Automate the cleanup of stale ephemeral environments with a solution [like Odin](https://github.com/manwaring-automation/odin)\n\n\\* Note that these kinds of pipelines work best using [trunk based development](https://trunkbaseddevelopment.com/)\n","readmeFilename":"README.md"}
![](\"https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/serverless-plugin-test-helper/readme-category-icon.png\"){kind=icon}
\n ![](\"https://d1wzvcwrgjaybe.cloudfront.net/repos/manwaring/serverless-plugin-test-helper/readme-repo-icon.png\"){kind=icon}
\n![](\"https://b7z7o7y5fi.execute-api.us-east-1.amazonaws.com/v1/readme/visits/github/manwaring/serverless-plugin-test-helper?style=flat-square\")