An example of creating a Full Stack project using functional testing as a design tool (continued)
Next, we will consider the same approach (design through the definition of functional tests) in relation to the remaining API part of the project and the release of the entire Full Stack project. We will use Python, although any other language can be used.
How did the web part help?
The created web part provides:
user registration;
registered user login;
displaying information about the user.
The web part can work without an API thanks to mocks. They will help us define more detailed goals of the API part.
Mocks defined in the web part (mocks.ts):
const mockAuthRequest = async (page: Page, url: string) => {
await page.route(url, async (route) => {
if (route.request().method() === 'GET') {
if (await route.request().headerValue('Authorization')) {
await route.fulfill({status: StatusCodes.OK})
}
}
})
}
export const mockUserExistance = async (page: Page, url: string) => {
await mockAuthRequest(page, url)
}
export const mockUserInfo = async (page: Page, url: string, expectedApiResponse: object) => {
await mockRequest(page, url, expectedApiResponse)
}
export const mockUserNotFound = async (page: Page, url: string) => {
await mockRequest(page, url, {}, StatusCodes.NOT_FOUND)
}
export const mockServerError = async (page: Page, url: string) => {
await mockRequest(page, url, {}, StatusCodes.INTERNAL_SERVER_ERROR)
}
export const mockUserAdd = async (page: Page, userInfo: UserInfo, url: string) => {
await mockRequest(page, url, {}, StatusCodes.CREATED, 'POST')
}
export const mockUserAddFail = async (page: Page, expectedApiResponse: object, url: string) => {
await mockRequest(page, url, expectedApiResponse, StatusCodes.BAD_REQUEST, 'POST')
}
export const mockExistingUserAddFail = async (page: Page, userInfo: UserInfo, url: string) => {
await mockRequest(page, url, {}, StatusCodes.CONFLICT, 'POST')
}
export const mockServerErrorUserAddFail = async (page: Page, url: string) => {
await mockRequest(page, url, {}, StatusCodes.INTERNAL_SERVER_ERROR, 'POST')
}Definition of goals and design
Based on the created web part, you can define API goals (use cases):
User authentication
Adding a user to the system
Deleting a user
Getting user information
From the web part tests we also get definitions of endpoints that should be implemented in the API:
To complete the functionality of the system, you should add the DELETE method for endpoint /user, although it is not used in the web project.
Tools (you can use any similar ones):
Defining tests
We create the project design in the same way as in the web part: first we define tests, and then we implement endpoints in the API server. Compared to the web part, API tests are much simpler. The test code for deleting, creating, user authentication and getting information can be viewed Here.
I will give only an example of tests and endpoint for deleting a user:
from hamcrest import assert_that, equal_to
from requests import request, codes, Response
from src.storage.UserInfoType import UserInfoType
from tests.constants import BASE_URL, USR_URL, USR_INFO_URL
from tests.functional.utils.user import add_user
class TestDeleteUser:
@staticmethod
def _deleting(user_name: str) -> Response:
url = f"{BASE_URL}/{USR_URL}/{user_name}"
return request("DELETE", url)
def test_delete_user(self, user_info: UserInfoType):
add_user(user_info)
response = self._deleting(user_info.name)
assert_that(
response.status_code,
equal_to(codes.ok),
"Invalid response status code",
)
url = f"{BASE_URL}/{USR_INFO_URL}/{user_info.name}"
response = request("GET", url)
assert_that(
response.status_code,
equal_to(codes.not_found),
"User is not deleted",
)
def test_delete_nonexistent_user(self, user_info: UserInfoType):
response = self._deleting(user_info.name)
assert_that(
response.status_code,
equal_to(codes.not_found),
"Invalid response status code",
)
def test_get_info_deleted_user(self, user_info: UserInfoType):
add_user(user_info)
self._deleting(user_info.name)
url = f"{BASE_URL}/{USR_INFO_URL}/{user_info.name}"
response = request("GET", url)
assert_that(
response.status_code,
equal_to(codes.not_found),
"User is not deleted",
)Server implementation
Defining endpoints in Falcon (app.py):
import falcon.asgi
from src.resources.UserInfo import UserInfo
from src.resources.UserOperations import UserOperations
from .resources.Health import Health
from .storage.UsersInfoStorage import UsersInfoStorage
from .storage.UsersInfoStorageInMemory import UsersInfoStorageInMemory
def create_app(storage: UsersInfoStorage = UsersInfoStorageInMemory()):
app = falcon.asgi.App(cors_enable=True)
usr_ops = UserOperations(storage)
usr_info = UserInfo(storage)
app.add_route("/user", usr_ops)
app.add_route("/user_info/{name}", usr_info)
app.add_route("/user/{name}", usr_ops)
app.add_route("/health", Health())
return appNext, we create stubs for the endpoints so that the server can start, and all tests at this stage fail. The code that returns a response with status 501 (Not Implemented) is used as a stub.
An example of stubs from one of the Falcon resource files:
class UserOperations:
def __init__(self, storage: UsersInfoStorage):
self._storage: UsersInfoStorage = storage
async def on_get(self, req: Request, resp: Response):
resp.status = HTTP_501
async def on_post(self, req: Request, resp: Response):
resp.status = HTTP_501
async def on_delete(self, _req: Request, resp: Response, name):
resp.status = HTTP_501Now, as in the previous part, we begin to replace the stubs with the necessary code until all tests pass (the final endpoints code can be viewed here).
This process is called “Red-Green-Refactor”
You should add an E2E test for the process of creating → authentication → deleting a user (e2e.py):
from hamcrest import assert_that, equal_to
from requests import request, codes
from src.storage.UserInfoType import UserInfoType
from tests.constants import BASE_URL, USR_URL, USR_INFO_URL
from tests.functional.utils.user import add_user
from tests.utils.auth import create_auth_headers
class TestE2E:
def test_e2e(self, user_info: UserInfoType):
add_user(user_info)
url = f"{BASE_URL}/{USR_URL}"
response = request("GET", url, headers=create_auth_headers(user_info))
assert_that(response.status_code, equal_to(codes.ok), "User is not authorized")
url = f"{BASE_URL}/{USR_INFO_URL}/{user_info.name}"
response = request("GET", url)
assert_that(
response.json(),
equal_to(dict(user_info)),
"Invalid user info",
)
url = f"{BASE_URL}/{USR_URL}/{user_info.name}"
request("DELETE", url)
url = f"{BASE_URL}/{USR_INFO_URL}/{user_info.name}"
response = request("GET", url)
assert_that(
response.status_code,
equal_to(codes.not_found),
"User should not be found",
)The result of creating the API part
In general, the process is similar to the previous part for the web, but shorter, since all the main goals have already been determined during the design and implementation of the web part. All that remained was to define tests for the API.
Project release
So, the Web and API parts of the project are ready and tested independently of each other.
All that remains is to connect them. An E2E functional test in the web part will help you do this.
Based on the project goals defined in the previous part, the project must provide the user with registration and login. This is exactly what will be tested in the E2E test.
import {expect, test} from "@playwright/test";
import axios from 'axios';
import {fail} from 'assert'
import {faker} from "@faker-js/faker";
import {buildUserInfo, UserInfo} from "./helpers/user_info";
import {RegistrationPage} from "../infra/page-objects/RegisterationPage";
import {RegistrationSucceededPage} from "../infra/page-objects/RegistrationSucceededPage";
import {LoginPage} from "../infra/page-objects/LoginPage";
import {WelcomePage} from "../infra/page-objects/WelcomePage";
const apiUrl = process.env.API_URL;
const apiUserUrl = `${apiUrl}/user`
async function createUser(): Promise<UserInfo> {
const userInfo = {
name: faker.internet.userName(),
password: faker.internet.password(),
last_name: faker.person.lastName(),
first_name: faker.person.firstName(),
}
try {
const response = await axios.post(apiUserUrl, userInfo)
expect(response.status, "Invalid status of creating user").toBe(axios.HttpStatusCode.Created)
} catch (e) {
fail(`Error while creating user info: ${e}`)
}
return userInfo
}
test.describe('E2E', {tag: '@e2e'}, () => {
let userInfo = null
test.describe.configure({mode: 'serial'});
test.beforeAll(() => {
expect(apiUrl, 'The API address is invalid').toBeDefined()
userInfo = buildUserInfo()
})
test.beforeEach(async ({baseURL}) => {
try {
const response = await axios.get(`${apiUrl}/health`)
expect(response.status, 'Incorrect health status of the API service').toBe(axios.HttpStatusCode.Ok)
} catch (error) {
fail('API service is unreachable')
}
try {
const response = await axios.get(`${baseURL}/health`)
expect(response.status, 'The Web App service is not reachable').toBe(axios.HttpStatusCode.Ok)
} catch (error) {
fail('Web App service is unreachable')
}
})
test("user should pass registration", async ({page}) => {
const registerPage = await new RegistrationPage(page).open()
await registerPage.registerUser(userInfo)
const successPage = new RegistrationSucceededPage(page)
expect(await successPage.isOpen(), `The page ${successPage.name} is not open`).toBeTruthy()
})
test("user should login", async ({page}) => {
const loginPage = await new LoginPage(page).open()
await loginPage.login({username: userInfo.name, password: userInfo.password})
const welcomePage = new WelcomePage(userInfo.name, page)
expect(await welcomePage.isOpen(), `User is not on the ${welcomePage.name}`).toBeTruthy()
})
});It's important to note that this is a sequence of tests. Unlike the previous examples, where the tests were independent and could be executed in parallel, here the tests are interconnected and executed sequentially. Additionally, these tests do not use any mocks.
The Web and API parts of the project can be launched as separate services using Docker containers.
Dockerfile for the API part:
FROM python:3.11-alpine
ENV POETRY_VERSION=1.8.1
ENV PORT=8000
WORKDIR /app
COPY . .
RUN apk --no-cache add curl && pip install "poetry==$POETRY_VERSION" && poetry install --no-root --only=dev
EXPOSE $PORT
CMD ["sh", "-c", "poetry run uvicorn src.asgi:app --log-level trace --host 0.0.0.0 --port $PORT"]Dockerfile for the Web part:
FROM node:22.7.0-alpine
WORKDIR /app
COPY . .
ENV API_URL="http://localhost:8000"
ENV WEB_APP_PORT="3000"
RUN apk --no-cache add curl && npm install --production && npm run build
EXPOSE $WEB_APP_PORT
CMD ["npm", "start"]Or both services at once as a docker composition:
services:
web:
image: web
container_name: web-app
ports:
- "3000:3000"
environment:
- API_URL=http://api:8000
depends_on:
api:
condition: service_healthy
healthcheck:
test: [ "CMD", "curl", "-f", "http://localhost:3000/health" ]
interval: 5s
timeout: 5s
retries: 3
api:
image: api
container_name: api-service
ports:
- "8000:8000"
healthcheck:
test: [ "CMD", "curl", "-f", "http://localhost:8000/health" ]
interval: 5s
timeout: 5s
retries: 3
networks:
default:
name: my-networkFor the convenience of running both services locally, an E2E test has been added script.
It is worth noting that the ability to run the entire product locally or its individual parts is one of the signs of its suitability for testing and ease of development.
Tests should be part of the CI/CD process, so I added as an example workflows to the GitHub repository. After each commit to the repository, the following workflows are launched:
API – assembly of this part of the project and launching its tests. Code Here.
Web – assembling this part of the project, launching the web service and testing it. Code Here.
E2E – launching a Docker composition of both parts and testing it using the E2E test. Code Here.
Bottom line
In general, the process of designing a Full Stack project was considered by defining functional tests sequentially for the web and API parts and implementing the project code in parallel with the implementation of the test code. This makes it possible to gradually define and move from the overall goals of the project to their more detailed parts, without losing control of the quality and integrity of the project.
The example project is very simple; Naturally, in reality projects are much more complex. Therefore, this design method is more suitable for designing individual features.
As already mentioned in the previous part, one of the disadvantages of the approach is the development time.
Another disadvantage is the separation of the created parts of the project, that is, their lack of synchronization with respect to subsequent changes. For example, if changes are made to the endpoints in the API part, the web part will not know about it.
This problem can be solved either by synchronization within the development team (if it is small and the frequency of changes in the API is low), or by using design by contract.
Thank you!
