API User Stories & Testing Hints for Naafe' App

Prepared By:

Ahmed Walid Abdulmaaboud

Basant Mohamed Elsaey
Mohamed Gamal Shoaib
Mohamed Hamdien Abdelkader
Yahya Hassan Mohamed

Information Technology Institute (ITI)

ITIInfo@[Link] | +202-35355656 | [Link]
Date: 18/07/2025

Contents

1 Introduction

2 Auth Routes

3 User Routes

4 Category Routes

5 Job Request Routes

6 Offer Routes

7 Listing Routes
1 Introduction

This document outlines user stories and testing hints for the main API routes of the Naafe' app, a platform connecting
Egyptians seeking or offering local services. Each user story describes the user's goal, followed by testing suggestions,
including edge cases and expected behaviors. Note that some routes are still under development.

Note: Some routes are under development and may require additional testing as they are finalized.

2 Auth Routes

2.1 POST /api/auth/register

User Story: As a new user, I want to register an account so that I can use the platform.

Testing Hints

Test with valid and invalid email formats.

Test password strength requirements (e.g., 8+ characters, mixed case, numbers, special characters).
Try registering with an already used email (should fail with a 400 status).
Check required fields (missing username, email, or password should return validation errors).

2.2 POST /api/auth/login

User Story: As a registered user, I want to log in so I can access my account.

Testing Hints

Test with correct and incorrect credentials.

Test login with unregistered email (should fail with a 401 status).
Test login with deactivated or blocked accounts (should fail with a 403 status).
Check response includes a valid JWT token.
3 User Routes

Endpoint User Story Testing Hints

GET /api/users/me As a logged-in user, I want to view my profile

Test with valid and invalid/expired tokens.
information.
Ensure sensitive fields (like password) are not returned.

PATCH /api/users/me As a logged-in user, I want to update my profile

Test updating each field individually and all at once.
information.
Test with missing/invalid fields (e.g., invalid email format).

Try updating with an email already in use by another user (should

fail).

GET As a logged-in user, I want to see all my job requests.

Test with users who have requests and those who have none.
/api/users/me/requests
Test with invalid/expired tokens (should fail with a 401 status).

GET /api/users/:id As any user, I want to view another user's public

Test with valid and invalid user IDs.
profile.
Test with non-existent user IDs (should return 404).
Check that only public information is returned.

GET /api/users/ As an admin, I want to view all users in the system.

Test with admin and non-admin tokens (non-admin should fail
with 403).
Test pagination and filtering (if supported).

PATCH As an admin, I want to block a user to restrict their

Test with admin and non-admin tokens (non-admin should fail).
/api/users/:id/block access.
Try blocking an already blocked user (should handle gracefully).
Test with invalid user IDs (should return 400).

PATCH As an admin, I want to unblock a previously blocked

Test with admin and non-admin tokens (non-admin should fail).
/api/users/:id/unblock user.
Try unblocking a user who is not blocked (should handle
gracefully).

Test with invalid user IDs (should return 400).

4 Category Routes

Endpoint User Story Testing Hints

GET /api/categories As any user, I want to view all available categories.

Test with and without authentication.
Test when no categories exist (should return empty array).

GET /api/categories/:id As any user, I want to view details of a specific

Test with valid and invalid category IDs.
category.
Test with non-existent category IDs (should return 404).

POST /api/categories As an admin, I want to create a new category.

Test with admin and non-admin tokens (non-admin should fail).
Test with missing/invalid fields (e.g., missing name).

Try creating a category with a duplicate name (should fail).

PUT /api/categories/:id As an admin, I want to update an existing category.

Test with admin and non-admin tokens (non-admin should fail).

Test with valid and invalid category IDs.

Try updating to a duplicate name (should fail).

DELETE As an admin, I want to delete a category.

Test with admin and non-admin tokens (non-admin should fail).
/api/categories/:id
Test with valid and invalid category IDs.
Try deleting a category that is in use (should handle gracefully).

5 Job Request Routes

Endpoint User Story Testing Hints

POST /api/requests As a seeker/provider, I want to create a new job request.

Test with valid and invalid tokens.

Test with missing/invalid fields (e.g., missing title).

Test with both seeker and provider roles.

GET /api/requests As any user, I want to view all job requests (with filters).
Test with and without authentication.
Test filtering and pagination (if supported).

GET /api/requests/:id As any user, I want to view a specific job request.

Test with valid and invalid job request IDs.

Test with non-existent job request IDs (should return 404).

PATCH /api/requests/:id As the owner or admin, I want to update a job request.

Test with owner, admin, and unrelated user tokens.
Test with valid and invalid job request IDs.

Test updating with invalid data (e.g., invalid budget).

DELETE /api/requests/:id As the owner or admin, I want to delete a job request.

Test with owner, admin, and unrelated user tokens.
Test with valid and invalid job request IDs.

POST /api/requests/:id/offers As a provider, I want to make an offer on a job request.

Test with provider, seeker, and unauthenticated tokens.

Test with valid and invalid job request IDs.

Test with missing/invalid offer data (e.g., missing price).

GET /api/requests/:id/offers As any user, I want to see all offers for a job request.
Test with owner, admin, and unrelated user tokens.

Test with valid and invalid job request IDs.

6 Offer Routes

Endpoint User Story Testing Hints

GET /api/offers As a provider or seeker, I want to view offers related to me.

Test with provider, seeker, and unauthenticated tokens.

Test filtering (if supported, e.g., by status or job request).

GET /api/offers/:offerId As an authorized user, I want to view a specific offer.

Test with valid and invalid offer IDs.
Test with unauthorized users (should fail with 403).

PATCH /api/offers/:offerId As the offer owner, I want to update my offer.

Test with owner and non-owner tokens.

Test with valid and invalid offer IDs.

Test updating with invalid data (e.g., negative price).

DELETE /api/offers/:offerId As the offer owner, I want to delete my offer.

Test with owner and non-owner tokens.

Test with valid and invalid offer IDs.

7 Listing Routes

Endpoint User Story Testing Hints

GET /api/listings As any user, I want to view all service listings.

Test with and without authentication.

Test filtering and pagination (if supported).

POST /api/listings As a seeker/provider, I want to create a new service

Test with valid and invalid tokens.
listing.
Test with missing/invalid fields (e.g., missing title).

GET /api/listings/:id As any user, I want to view a specific service listing.

Test with valid and invalid listing IDs.

Test with non-existent listing IDs (should return 404).

PATCH /api/listings/:id As the provider, I want to update my service listing.

Test with owner and non-owner tokens.
Test with valid and invalid listing IDs.

Test updating with invalid data (e.g., negative price).

DELETE /api/listings/:id As the provider, I want to delete my service listing.

Test with owner and non-owner tokens.
Test with valid and invalid listing IDs.

GET As a provider, I want to view all my own listings.

Test with provider and non-provider tokens.
/api/users/me/listings
Test with and without listings (should return empty array if none).