DEV Community: Daniel Haimov

Functional Testing as a Design Tool for Full Stack Projects. Part II: API server and Project Release

Daniel Haimov — Sat, 12 Oct 2024 18:25:24 +0000

In the previous part of this article, we implemented the general design of the Full Stack project. We also designed and implemented the web part of the project using functional tests. I recommend revisiting the previous part for a clearer understanding of the material covered so far.

In this part, we’ll apply the same approach — design via functional test definitions — to the API part of the project and its release.

For implementing the API part, we’ll use Python (though any other language could be used as well).

How has the Web part helped?

The implemented web part provides:

User registration
Sign-in for registered users
Display of user information

As demonstrated, the web part can run without a connection to the API part, thanks to the use of mocks.

These mocks can help us define the detailed purposes of the API part.

The mocks defined in the Web part (mocks.ts) are:

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')
}

Defining API Purposes and Design

Based on the developed Web part, let’s outline the API’s key purposes (use cases):

User authentication
Adding a user to the system
Deleting a user from the system
Retrieving user information

From the Web part’s functional tests, we’ve derived the following endpoint definitions for the API:

/user — supporting GET and POST methods
/user_info/${username} — supporting GET method

To achieve full functionality, we should add a DELETE method to the /user endpoint, even though it wasn’t utilized in the Web part.

Here’s the general design of the API part:

Tools we’ll use (though similar alternatives could be substituted):

Falcon — a lightning-fast, minimalist Python web API framework for building robust app back-ends and micro-services
Pytest — a framework that simplifies writing small, readable tests and scales to support complex functional testing for applications and libraries

Test Definition

We’ll implement the API part’s design following the same approach as in the previous part:

Define the functional tests
Implement the endpoints in the API server

The API’s functional tests are more straightforward than those in the Web part. You can find the test code here. As an example, let’s look at the tests for deleting a user and the corresponding endpoint.

Here are the tests for deleting a user (delete_user.py):

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",
        )

API Server Implementation

The endpoints definition 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 app

Now it’s time to stub the endpoints. This allows us to run the API server, though all tests will initially fail. For our stub, we’ll use code that returns a response with the status code 501 (Not Implemented).

Here’s an example of the stubs in one of the resource files of our Falcon app:

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_501

Let’s replace each stub with the required code, as demonstrated in the web part, until all tests pass. (The final code for the endpoints can be found here.)

The process is called Red-Green-Refactor:

Here’s an example of replacing a stub with real code in the endpoint for deleting a user:

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):
        try:
            self._storage.delete(name)
            resp.status = HTTP_200
        except ValueError as e:
            update_error_response(e, HTTP_404, resp)

An E2E test should be added to verify the complete process of adding a user → authenticating → deleting the 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",
        )

Summary of the API Part Development Process

Overall, the process mirrors that of the Web part but is more streamlined. This is because we’ve already defined the general purposes during the Web development stage. Our focus here is primarily on defining the functional tests for the API.

With both the Web and API parts of the project now complete and independently tested, we move to the final stage.

Release of the Whole Project

The last step is to integrate the Web and API components. We’ll use End-to-End (E2E) testing in the Web part to facilitate this integration. As we defined earlier, the main purpose of the project is to enable user registration and sign-in. Therefore, our E2E test should verify the entire process of user registration and subsequent sign-in in one comprehensive test sequence.

It’s worth noting that E2E tests don’t use mocks. Instead, they interact directly with the Web app connected to the API server, simulating real-world usage. (e2e.spec.ts)

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()
    })
});

As you can see, this is a sequence of tests. All the previously described tests in the Web and API parts are independent and can be run in parallel.

The Web and API components can be run separately as independent services via Docker containers.

Here’s the Dockerfile for the API server:

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"]

Here’s the Dockerfile of the Web app:

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"]

The Docker composition of the both parts:

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-network

There is a script for a more convenient way of running E2E tests with the services.

It's worth noting that the ability to run the entire project or its parts separately locally demonstrates the project's testability and ease of development.

Testing should be an integral part of the CI/CD process. Therefore, workflows for CI/CD have been added to the project's repository on GitHub.

The following workflows run for each commit to the repository:

API - build and testing
Web - build, run as a service, and testing
E2E - run both services and perform E2E testing

Conclusion

These two parts have demonstrated how to design a Full Stack project through functional test definition. Both the Web and API parts have been designed and developed independently.

This approach allows for progression from general purpose definition to more detailed specifications without losing control of the project's quality and integrity.

While this project serves as a simple example, real-world projects are often more complex. Therefore, this method is particularly useful for designing separate features.

As mentioned earlier, one of the drawbacks of this approach is the time required for development.

Another drawback is the disconnection between project parts during development. This means there's no automatic synchronization of changes between parts. For example, if there's a code change in an endpoint definition in the API part, the Web part won't be automatically aware of it.

This issue can be addressed through human inter-team synchronization (in cases of small teams or low code change frequency) or by implementing Design by Contract methodology.

Functional Testing as a Design Tool for Full Stack Projects: A Simple Example

Daniel Haimov — Sat, 05 Oct 2024 07:44:31 +0000

Design a full-stack project by starting with its functional tests. Does that sound crazy?
In the sequence of articles, I'll demonstrate how to design the testing of a Full Stack project alongside the project's design itself, using a simple example. I'll also highlight the benefits of this approach.
The source code of the example project is here
Maybe this article will be helpful for Front-End/Back-End developers and automation test developers (or anyone else looking for a good night's sleep)

Defining Functional Testing

Many books and articles have been devoted to testing and its importance, so I'll skip that topic here. Instead, this article will focus on functional testing and its role in product design. Functional testing evaluates a product's functionality without relying on its internal implementation. For a more precise definition, you can refer to Wikipedia.

Why Do You Need Functional Testing?

During my career as an automation engineer, I have encountered many projects that were launched without functional tests from the outset. This stems from the misconception that functional tests should be added to a finished product and serve only for quality assurance. Without tests, the number of bugs and client complaints grows. Developers then rush to add tests, only to realize that adding functional tests to an existing product is not as easy as they thought.
The difficulty in adding functional tests at this stage lies in the product's lack of testability. When the product was designed, no one considered its automated testing needs.
Testability of a product can include:

The ability to run the product locally (e.g., building the product/environment from source code for each test run)
A complete product API for automated testing (e.g., automatic creation/deletion of a product's user/account for each test run)
The ability to implement mocking of product components or functionalities (e.g., replacing the product's database with a mock or emulator)

During the product design phase, it's much easier to design tests because you're not constrained by existing code, frameworks, or utilities embedded in the product's architecture.
In this article, I'll demonstrate how a simple web application can be designed (and implemented) using functional tests design.

Defining the General Design and Objectives

Let's define the main purposes of the project: user registration and presenting personal info after sign-in.
More specifically, the project should support:

User registration
Sign-in for registered users
Displaying user's personal info

The design should consist of two main parts:

API - for user administration and storing personal information
Web - for registration, sign-in, and displaying user info

Project components:

Notice the decoupling of the storage into a real instance and its mock. This enhances the product's testability and independence from any actual storage instance. As you might guess, this follows the Adapter design pattern.

Initial Design Steps

Let's begin with the Web part of the project. Why start here?
The Web part is the user's interface, helping us define the project's detailed purposes from the user's perspective (user stories). It also aids in determining the API part's requirements, as the Web part interacts directly with the API.

Test Definition and Implementation

Let's define a set of tests for each project purpose.
Registration tests:

User successfully completes registration with valid personal data
User fails registration when using invalid personal data (e.g., missing last name)
Existing user cannot register again
Registration fails due to server-side errors

Sign-in tests:

Existing user can sign in successfully
User's personal information is displayed after sign-in
User cannot sign in with invalid credentials
Sign-in fails due to server-side errors

These tests provide a detailed description of the project's general purposes. Implementing functional tests helps us understand the required web pages, their functionalities, user interactions, and the interconnection between the Web and API parts.

Each test follows the AAA (Arrange-Act-Assert) pattern:

Arrange - set up the test's precondition
Act - perform the action being tested
Assert - verify the result of the action

Our tests will interact with web page models (which correspond to real project web pages) and API server mocks.

Frameworks used (other similar ones can be substituted):

ExpressJS - web server
Playwright - functional tests

Components involved in testing the Web part:

The Example of the Registration page test run (sequence version):

Now, let’s examine the code for the tests we defined earlier:

RegistrationPage — the functional model of the registration page (also known as its Page Object Model or Page Object)
RegistrationSucceededPage — the functional model of the successful registration page

At this stage, we can’t implement the methods called in the tests because the actual web pages don’t exist yet. The same applies to the mock functions used in test preconditions, as we don’t know the API server’s requests and responses yet.

These methods and functions will be stubbed (learn about stubs here), initially returning invalid results to intentionally fail the tests.

So, what do we have now and how does it help?

An understanding of the real web pages’ functionality (through the test code)
A set of functional tests for the project’s web pages

Let’s Code it Up!

The project items still not implemented:

web server(using ExpressJS)
project web pages
API server interconnections(in the web pages)
stubs replacing by code in the Page Objects and in the mocks of the API server

I wont waste time on the describing of the web pages creation and the configuration of the web server. All the relating code is here. Just some examples

Web server (server.ts):

Registration page example (register.html):

The link between the registration page and the API server(register.ts):

The appearance of the registration page in various scenarios

During the development of the web pages, test stubs will be replaced with actual code. The same applies to mocks used in test preconditions.

Below is an example of implementing mocks using Playwright (the full code is here):

Once all tests pass, the web portion of the project can be considered complete.

Summary of the Web Part Development Process

This article outlined how to design the web portion of a project, starting from broad concepts and progressing to detailed components. During the web development process, requirements for the API server were defined, which will assist in its subsequent design.

The understanding of the web’s functionality was achieved by creating functional tests, followed by the parallel development of the web components alongside the tests. The functional tests run independently of the API server (which, at this stage, hasn’t yet been implemented).

This approach mirrors a gradual progression from general concepts to specific details, allowing better control over the entire design and development process while maintaining quality and a clear understanding. It enables the definition of essential project elements before their actual code implementation.

Overall, this process resembles the TDD (Test-Driven Development) methodology, applied here in the context of functional testing.

One drawback is the extended development time, which can be critical for startups where delivering features quickly may take precedence over quality. As a result, startup managers often remain skeptical of this method.

However, regular practice of this approach can reduce development time as experience and intuition grow.

The code for the web portion of the project is available here.

The next article will cover the API implementation and deployment of the entire Full Stack project.

Thank you!