Stub providers

The Dev, preview, staging and prod instanced of Notify are configured to make calls to Notify SMS providers for sending SMS, and AWS Simple Email Service (SES) for sending emails.

In some circumstances it may be desirable to configure a dev environment not to send live SMS or email notifications. The Notify provider stubs, are GO applications that mimic the API endpoints used by SES and our SMS providers, and provide valid responses. When enabled, Notify can be used with live API keys (and users can also use the admin interface) to send notifications, which will be sent to the provider stub and never delivered.

It is possible to use the notifications-performance-tests(https://github.com/alphagov/notifications-performance-tests) tool to create some simulated SMS and Email traffic if needed.

This is useful when debugging issue and completing performance tests.

The Load testing document has detailed instructions about how to enable the provider stubs and other settings needed for performance testing on the staging environment.

This document has short instructions on how to enable the provider stubs in dev environments, should they be needed.

Warning Please ensure you run the validation checks after enabling stubs to ensure they are working correctly (and avoid sending test notifications to suppliers which charge for processing messages). Please also make sure that you follow the tear down instructions carefully, to ensure that notifications sitting in SQS queues are not sent to providers when the stubs are disabled.

Setup

Setup your testing orgs

As mentioned above, the provider stubs mimic the supplier API endpoints for SMS and emails. Once enabled, the Notify instance you are testing will no longer be able to send emails or SMS to external recipients, and therefore you are unable to set up new users or sign in to the admin interface using a SMS or Email based 2FA code.

This means it is important to fully configure the test environment before enabling the stub-providers. Log in to the platform and set up the required test organisation, user, template, and API key required for the test. It is also recommended to have platform admin rights, and configure your yubikey as a second factor (so you can use this to log in to the admin app during a test if needed). More information can be found in the joiners process on how to do this.

Enable the provider stubs

To enable to provider stubs, create a new branch from the notifications-aws repo. Edit the terraform/notify-apps/tfvars/dev-[env].tfvars file. Towards the bottom of the file there is a section with load test setting:

### LOAD TESTING SETTINGS
stubs_enabled          = false
sentry_traces_disabled = false
stubs_deployed         = false
### END LOAD TESTING SETTINGS

Change all three settings to true. Push the branch to github and then follow the Controlling inputs to the deploy-notify pipeline instructions to deploy the notifications-aws change to the dev environment.

This change updates the provider API URLS to point to the provider stubs, rather than to our supplier's APIs.

Check the stubs are working

Important Before running any tests, check the provider stubs are working correctly. Use the Notify admin interface to send a SMS and email to yourself. You should see these messages marked as delivered, but no SMS or email is delivered.

You should also check the log output of the ECS provider stubs task. To do this, login to the AWS console for the dev environment using the GDS AWS tool, and navigate to the ECS service. Click on the notify cluster, then choose sms-provider-stub or email-provider-stub. Now click on the logs tab, and check that the recent notifications you have sent are showing up in the provider stub (which means it is the stub, not the third party supplier that has processed the message).

Disabling stubs

Before disabling the provider stubs ensure that all tests are finished, and that the SQS queues are empty.

Checking the SQS queues are empty

To check the SQS queues, login to the AWS console for the dev environment using the GDS AWS tool, and navigate to the SQS service. Check the number of messages available and messages in flight.

If you need to clear a queue manually (rather than wait), you may need to destroy the environment first (to prevent scheduled tasks from identifying unsent notifications in the DB and adding them back to the queues). Then from the AWS console, click on the radio next to the queue you wish to clear and click actions, purge.

Revert notifications-aws

Once you are happy that no notifications are being sent, and the queues are empty it is safe to revert notifications-aws by redeploying the MAIN branch or reverting the load test settings in the terraform/notify-apps/tfvars/dev-[env].tfvars file.