---
title: "Testing Guide: Real Estate Agent Role"
space: "testing-docs"
url: "https://qejaverse-prod.jh.frappe.cloud/testing-guide-real-estate-agent-role"
updated: "2026-08-15"
---

> **What is this?** A feature-by-feature reference for testers. Go through each section below, verify the expected behaviour, and log any issues you find.
>
> **App URL:** `https://casahub.jh.frappe.cloud/qeja`
>
> **Your role for this test:** Real Estate Agent


## 1. Registration

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | Go to `/qeja` and click **Create Account** | Sign-up form appears |
| 2a | Enter first name, last name, email, password and submit | Account is created, you are logged in automatically |
| 2b | Or click **Sign in with Google** | Google OAuth flow completes, account is created |
| 3 | After sign-up | You land on `/onboarding-check` -- you cannot access any dashboard yet |

**Things to check:**

- Duplicate email is rejected with a clear message

- Password requires 8+ characters

- Empty required fields show validation errors

- Welcome email arrives


## 2. Login

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | Go to `/qeja/login`, enter credentials | Logged in successfully |
| 2a | If onboarding incomplete | Redirected to `/onboarding-check` |
| 2b | If onboarding complete | Redirected to `/agent/dashboard` |
| 3 | Wrong password | Clear error message, not a generic server error |
| 4 | Forgot password link | Password reset email is sent |


## 3. Logout

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | Click profile/avatar in sidebar, click **Logout** | Session ends, redirected to login page |
| 2 | Try to visit `/agent/dashboard` directly | Redirected to login -- no access |


## 4. Onboarding -- Profile Completion

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | You land on `/onboarding/profile` | Form shows: phone number (with +254 default), gender, date of birth |
| 2 | Fill in all fields and click **Continue** | Data saves, you move to `/onboarding/role` |
| 3 | Try to skip without filling required fields | Validation blocks you |


## 5. Onboarding -- Role Selection

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | You land on `/onboarding/role` | 4 role cards displayed |
| 2 | Click **Real Estate Agent** | Card highlights with a checkmark |
| 3 | Click **Continue** | You are assigned the agent role and land on `/agent/dashboard` |

**Things to check:**
- Only one role selectable at a time
- Cannot proceed without selecting
- Onboarding does not repeat on next login


## 6. Agent Profile

This is your professional profile visible to developers/managers in the agent directory.

### 6a. Profile Setup & Editing

| Section | Fields to fill | Expected behaviour |
|---------|---------------|--------------------|
| Personal info | Bio, years of experience | Saves; completeness % updates |
| Identification | ID type (National ID, Passport, etc.), ID number | Saves with validation |
| Company info | Company name, registration, website, phone | All optional; saves correctly |
| License info | License number, issuing authority, expiry date | Saves; expiry tracked for reminders |
| Specializations | Property types, specializations (multi-select from registry) | Saves; values come from system registry |
| Languages | Languages spoken (multi-select) | Saves correctly |
| Communication | Preferred method (Phone, Email, WhatsApp, SMS) | Single select; saves |
| Social media | LinkedIn, Facebook, Instagram, Twitter/X URLs | Saves as link pairs |

**Things to check:**
- Profile completeness percentage updates as you fill fields
- Real-time validation and save feedback (success/error toast)

### 6b. Profile Publishing

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Publish | Click **Publish** | Profile appears in Agent Directory; requires minimum fields filled |
| Unpublish | Click **Unpublish** | Profile removed from directory |
| Status | Check profile status display | Shows Draft, Active, Inactive, or Suspended |
| Published date | Publish profile | Published date auto-set |

### 6c. Document Uploads (KYC)

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Upload document | Click upload, select type (ID Copy, License Certificate, Tax Certificate, Insurance, etc.) | File uploads with correct document type |
| View documents | Go to documents section | All uploaded docs listed with type, name, date, expiry, verification status |
| Expiry tracking | Upload a doc with expiry date | System tracks expiry; reminder sent when approaching |
| Verification status | View a document | Shows: Pending, Verified, Rejected, or Expired |

**Things to check:**

- Can upload multiple document types

- File upload shows progress

- Cannot proceed to some features without KYC documents submitted

### 6d. KYC Status

| Status | What it means |
|--------|--------------|
| Not Started | No documents uploaded |
| Incomplete | Some documents uploaded but not all required |
| Profile Complete | All required fields and docs submitted |
| Verified | Admin has verified your documents |
| Rejected | Admin rejected -- reason should be visible |

---

## 7. Agent Dashboard

| Section | What you should see | Expected behaviour |
|---------|--------------------|--------------------|
| Quick stats | Active Projects, Total Leads, Conversion Rate %, Total Commissions | Values match actual data |
| Performance | Total projects, access requests submitted, approval rate, units sold, revenue generated | Accurate counts |
| Profile completion | Completeness % with missing field hints | Percentage matches profile state |
| Visibility status | Published/Not Published badge, Verified/Not Verified, License status | Matches actual profile |
| Rating & reviews | Average rating, total reviews | Matches actual reviews (if any) |

**Things to check:**

- Dashboard loads without errors or stuck spinners

- All stat values are accurate

- No console errors

---

## 8. Project Discovery

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Browse projects | Click **Projects** in sidebar | Grid/list of available projects seeking agents |
| View project details | Click a project card | Project detail page: name, location, units, pricing, payment plans, commission structure |
| Filter projects | Filter by location, price range, unit types, status | Results update correctly |
| Commission info | View commission section on a project | Shows commission rate/type for agents |

**Things to check:**

- Only published projects are visible

- Project details load fully (images, stats, developer info)

- Unpublished or draft projects are not shown


## 9. Project Access Requests

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Request access | Click **Request Access** on a project | Modal/form appears for motivation message |
| Submit request | Enter message and submit | Request created with "Pending" status; toast confirms |
| View my requests | Go to `/agent/applications?tab=requests` | All your requests listed with project, date, status |
| Withdraw request | Click **Withdraw** on a pending request | Request withdrawn; status updates |
| Approved request | After manager approves | Status changes to Approved; you now have access to the project |
| Rejected request | After manager rejects | Status changes to Rejected; reason visible |

**Things to check:**

- Cannot request access to same project twice

- Notification arrives when request is approved/rejected

- After approval, project appears in your active projects

- Withdrawal only works on pending requests


## 10. Lead Management

This is the core CRM feature for agents.

### 10a. Create Lead

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | Navigate to `/agent/leads`, click **Create Lead** | Lead form appears |
| 2 | Fill required fields: lead name, phone, project | Validation enforces required fields |
| 3 | Fill optional fields: email, source, budget range, preferred unit type, priority, notes | All save correctly |
| 4 | Submit | Lead created with auto-generated number (LEAD-.YYYY-.#####); stage defaults to "New" |

**Things to check:**

- Phone number auto-normalizes

- Can only create leads for projects you have access to

- Lead priority options: Hot, Warm, Cold

- Lead source options: Direct, Website, Referral, Portal, Event, etc.

### 10b. Lead Pipeline

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| View all leads | Open leads page | Table of all your leads with pagination (20/page) |
| Filter by stage | Select a stage filter | Only leads in that stage shown |
| Filter by priority | Select Hot/Warm/Cold | Filters correctly |
| Filter by project | Select a project | Only leads for that project shown |
| Search | Type name, phone, or email | Matching leads shown |
| Lead stats | View summary section | Total leads, leads by stage, by priority, conversion rate |

### 10c. Lead Stage Transitions

Leads move through this pipeline:

| Stage | Description |
|-------|-------------|
| New | Just created, not yet contacted |
| Contacted | Initial contact made |
| Viewing Scheduled | Property viewing appointment set |
| Viewing Done | Viewing completed |
| Negotiating | Price/terms discussion in progress |
| Booking | Client ready to book a unit |
| Converted | Lead became a paying customer |
| Lost | Lead did not convert |

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Change stage | Click a lead, change stage dropdown | Stage updates; activity logged |
| Mark as lost | Click **Mark Lost**, enter reason and notes | Lead moves to Lost; reason saved |
| Set follow-up | Set next follow-up date | Date saved and visible in lead detail |

### 10d. Lead Activities

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Log activity | On a lead, click **Log Activity** | Form: activity type, summary, outcome |
| Activity types | Select from: Call, Meeting, Site Visit, Email, SMS, Follow-up, Note, Other | Saves with timestamp |
| View timeline | Open lead detail | Full activity history in chronological order |
| Search activities | Search/filter activities | Results filter correctly |

### 10e. Lead Conversion

| Step | What to do | Expected result |
|------|-----------|----------------|
| 1 | Open a lead in Booking stage, click **Convert** | Conversion form appears |
| 2 | Select target unit from project inventory | Unit dropdown shows available units |
| 3 | Select payment plan template (if available) | Plan applies |
| 4 | Confirm conversion | Customer record created; payment schedule generated; lead marked "Converted" |
| 5 | After conversion | Lead shows converted date, unit, and customer reference |

**Things to check:**

- Only leads in appropriate stages can be converted

- Unit is reserved/booked after conversion

- Manager is notified of the conversion

- Cannot convert a lead that is already converted or lost


## 11. Contracts

### 11a. View Contracts

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| View all contracts | Go to `/agent/applications?tab=contracts` | List of contracts from managers with status, project, dates |
| Contract statuses | Check status badges | Draft, Sent, Pending Review, Active, Completed, Terminated, Declined |
| View details | Click a contract | Shows: title, type, project, dates, commission terms, content, timeline |

### 11b. Respond to Contracts

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| Accept contract | Click **Accept** on a sent contract | Status changes; you proceed to signing |
| Decline contract | Click **Decline**, enter reason | Status changes to Declined; manager notified |
| Upload signed doc | After accepting, upload signed document | Document attached to contract |
| View timeline | Check contract timeline | All status changes and actions logged with dates |

### 11c. Commission Terms

| What to look for | Expected display |
|------------------|-----------------|
| Commission rate | Percentage or fixed amount shown per contract |
| Commission type | "Percentage of unit price" or "Fixed amount per unit" |
| Override notes | Any custom commission notes from manager |


## 12. Commissions

| Feature | What to do | Expected result |
|---------|-----------|----------------|
| View dashboard | Go to `/agent/commissions` | Summary cards: Total Earned, Pending, Paid, Average per transaction |
| View list | Scroll to commissions table | All commissions listed with pagination (20/page) |
| Filter by status | Filter: Pending, Approved, Paid, Receipt Confirmed, Rejected | List filters correctly |
| Sort | Sort by date, amount, status, project | Sorting works |
| Search | Search by project, unit, or reference | Results filter |
| View detail | Click a commission | Shows: project, unit, price, calculation, amount, payment date, method, status |
| Confirm receipt | On a "Paid" commission, click **Confirm Receipt** | Status changes to Receipt Confirmed |

**Things to check:**

- Commission amounts match expected calculations (rate x unit price)

- Pending commissions are awaiting manager approval

- Payment proof/receipt visible when provided


## 13. Route Access / Permissions

| Route | Should you have access? |
|-------|------------------------|
| `/agent/dashboard` | Yes |
| `/agent/leads` | Yes |
| `/agent/commissions` | Yes |
| `/agent/applications` | Yes |
| `/projects` | Yes (browse published projects) |
| `/projects/:id` | Yes |
| `/profile` | Yes |
| `/manager/*` | No -- should redirect to `/unauthorized` |
| `/admin/*` | No -- should redirect to `/unauthorized` |
| `/owner/*` | No -- should redirect to `/unauthorized` |


## 14. Notifications

| Event | Expected notification |
|-------|---------------------|
| Access request approved | In-app + email notification |
| Access request rejected | In-app + email with rejection reason |
| Contract sent to you | Email notification with contract details |
| Contract activated | In-app notification |
| Contract terminated | In-app + email with reason |
| Commission approved | In-app notification |
| Commission paid | In-app notification |


## Quick Checklist Summary

Use this to track your progress:
- [ ] Mobile Responsiveness
- [ ] Registration (email + Google SSO)
- [ ] Login / Logout
- [ ] Onboarding (profile + role selection as Agent)
- [ ] Dashboard loads with correct data
- [ ] Agent profile: fill all sections, completeness % updates
- [ ] Agent profile: publish / unpublish
- [ ] Document uploads: multiple types, expiry tracking
- [ ] KYC status reflects document state
- [ ] Browse available projects
- [ ] Submit project access request
- [ ] View my access requests + statuses
- [ ] Withdraw a pending request
- [ ] After approval: project appears in my active projects
- [ ] Create a lead with all fields
- [ ] View lead list with search/filter/pagination
- [ ] Change lead stages through pipeline
- [ ] Log activities on leads (calls, meetings, visits, etc.)
- [ ] Mark a lead as lost with reason
- [ ] Convert a lead to customer (unit selection + payment plan)
- [ ] View contracts list
- [ ] Accept/decline a contract
- [ ] Upload signed contract document
- [ ] View contract details and timeline
- [ ] View commission dashboard and summary
- [ ] Filter/sort/search commissions
- [ ] View commission detail
- [ ] Confirm commission receipt
- [ ] Route permissions: cannot access manager/admin/owner routes
- [ ] Notifications arrive for key events