In this repository you will find a minimal web application built with FastAPI and the Vonage Verify API. Users can request a OTP password code sent to their email address. Upon entering the correct code into the app, users are rewarded with an animated gif.
This repository also serves as part of a workshop on using mocks in unit tests for better testing.
- OTP Code Generation: Generate a OTP code
- OTP Code Email Delivery: Use email to receive a OTP code
- Verification: Verify that the code provided by the user matches the code generated by Vonage
- Unit tests with mock examples: The unit tests use mocks of the Verify API for testing
- Python 3.8+
- A Vonage API account
- A GitHub account (if you want to run this code in Codespaces)
Vonage is a cloud-based communications platform that gives you the tools to embed communication capabilities directly into your own applications and services.
Rather than building communication infrastructure from scratch, you can use Vonage APIs to add voice, video, messaging, verification, and other network-level capabilities to products.
To run the code in this repo, you need a Vonage developer account and a Verify application.
You will need a Vonage API account -- it's free to sign up!
Create your Verify application in the developer dashboard by navigating to the Applications window from the left hand menu and clicking the “Create new application” button. This will open the application creation menu. Give your application a human-friendly name like vonage-hello-world.
Under the Capabilities section, toggle the option for Verify.
Click the “Generate new application” (or "Saves changes") button at the bottom of the application menu.
There are two ways you can run this code:
The biggest difference between the two is how each method handles secrets.
In the developer dashboard Applications menu, click on your application and then click Edit. Once the edit window opens, click on the button that says, “Generate public and private key”. This will trigger a download of your private key as a file with the extension .key. Keep this file private and do not share it anywhere it could be compromised.
Click on the "Save changes button" and also note your Application ID.
In summary, these are the secrets you will need from Vonage in order for your app to work:
| Variable name | Variable value |
|---|---|
| VONAGE_APPLICATION_ID | This is the Vonage-generated ID of the Voice application you created for this sample code |
| VONAGE_PRIVATE_KEY_PATH | This is the path to the private.key file you downloaded from the developer dashboard |
Clone this repo and change directories to the project directory:
git clone https://github.com/Vonage-Community/workshop-verify-python-mocks-example.git && cd workshop-verify-python-mocks-example
Set up your environment by first creating and activating a Python virtual environment:
virtuanlenv venv && source venv/bin/activate
Then install the project dependencies:
pip install -r requirements.txt
Move your private key file to your project directory and configure the variables in the .env_template file accordingly:
VONAGE_APPLICATION_ID=your-application-id
VONAGE_PRIVATE_KEY_PATH=path-to-your-private-key-file
Then update the name of the file from .env_template to .env. You can learn more about handling environment variables in Python here.
To spin up the app, run the following from the project root directory:
fastapi dev
Now you can try out the sample email verification app.
GitHub Codespaces is a cloud-based online integrated development environment developed by GitHub.
First fork this repo to your own GitHub account.
- In the upper-right corner of any page on GitHub, click your profile picture, then click Settings
- In the sidebar, under "Code, planning, and automation", select Codespaces
- To the right of Codespaces secrets, click New secret
- Under Name, type or copy and paste
VONAGE_APPLICATION_ID - Under Value, copy and paste in the application ID you obtained earlier from the Vonage developer dashboard
- Select the "Repository access" drop-down menu, then click on the name of this repository (
workshop-verify-python-mocks-example) - Select Add secret
- Repeat steps 4 - 7, this time with the Name
VONAGE_PRIVATE_KEY_PATHand the Value copied and pasted from the contents of theprivate.keyfile downloaded from the Vonage developer dashboard
For more information on adding secrets to Codespaces, refer to the GitHub documentation.
From the forked repo in your GitHub account, click the green "Code" button and from the menu that appears, select the "Codespaces" tab. Then click the green "Create codespace" button.
This will open up a new browser tab and begin the creation of a new codespace. It will take a few moments to complete the process.
To learn more about creating a codespace, please refer to the GitHub documentation.
To spin up the app, run the following in the codespace terminal:
fastapi dev
Now you can try out the sample email verification app.
Whether you are running the app locally or on GitHub Codespaces, in your browser, navigate to http://127.0.0.1:8000. You should see a webpage inviting you to "Try out the Vonage Verify
API by providing your email" with a text field for your email address.
You should be redirected to a page that asks you to provide the code sent to your email. Check your email for a OTP code from verify[at]vonage.com and enter this code.
If the code provided matches the code generated and sent by Vonage, then you'll be redirected to another page featuring an animated gif.
This repo also contains a suite of unit tests for the routes in main.py (tests/test_main.py). These tests use Python's unittest and builtin mock tools to simulate calls to the Vonage API.
Run the tests with the following command:
python -m unittest tests/test_main.py -v