🗺️ User Journey Documentation Guide

Technical documentation for implementing and maintaining user journeys

🏠 Home 🏗️ Architecture 📋 Survey Questions 🎓 Seminary Guide 🗺️ User Journeys ⚡ Quick Reference 🚀 SDLC

📚 What is User Journey Documentation?

The user journey documentation is a single source of truth that describes how different types of users interact with the application. It serves dual purposes:

  1. Documentation - Human-readable guides for stakeholders, developers, and testers
  2. Test Automation - Machine-readable data that E2E tests can reference

🎭 Three Personas

The application supports three distinct user personas:

👤
Personal Survey User

Individual users who use the app for personal spiritual leadership assessment.

Journey Steps: Sign-Up → Sign-In → Create Personal Survey → View Profile → Edit Survey → Retake Survey → Verify Updates → Sign-Out

🏛️
Organization Member

Users who belong to a church or ministry organization and participate in team assessments.

Journey Steps: Sign-Up/In → Join Organization → View Dashboard → Take Org Survey → View Survey Matrix → Compare Members → View Member Survey → Invite Members → Edit Settings → Switch Context

🔑
Super Administrator

System administrators with elevated privileges.

Journey Steps: Admin Sign-In → View All Organizations → Access Member Management → Delete User Account → Delete Organization → Move Personal Survey → View All Personal Surveys → Monitor System Health

📁 File Locations

Documentation Files

View Online

🔧 Using in E2E Tests

Import the Helper

import { getJourney, getJourneyStep, getStepTestData, getStepValidations, PERSONA_IDS, PERSONAL_USER_STEPS, } from './helpers/user-journey.helper';

Load Journey Data

// Get entire journey for a persona const personalJourney = getJourney(PERSONA_IDS.PERSONAL_USER); // Get specific step const signupStep = getJourneyStep( PERSONA_IDS.PERSONAL_USER, PERSONAL_USER_STEPS.SIGNUP ); // Get test data for a step const testData = getStepTestData( PERSONA_IDS.PERSONAL_USER, PERSONAL_USER_STEPS.SIGNUP ); // Get validations for a step const validations = getStepValidations( PERSONA_IDS.PERSONAL_USER, PERSONAL_USER_STEPS.SIGNUP );

Example Test

test('User Sign-Up using journey data', async ({ authPage, page }) => { // Load journey step const step = getJourneyStep(PERSONA_IDS.PERSONAL_USER, PERSONAL_USER_STEPS.SIGNUP); const testData = step.testData; console.log(`\n=== ${step.title} ===`); console.log(`Goal: ${step.userGoal}`); // Use test data from journey await authPage.goto(); await authPage.signUp( testData.firstName, testData.lastName, `test-${Date.now()}@example.com`, // Dynamic email testData.password ); // Validate using journey validations await expect(page).toHaveURL(/home/); console.log(`✅ Validated ${step.validations.length} assertions from journey`); });

📊 Journey Data Structure

Step Structure

Each journey step contains:

{ "id": "signup", "order": 1, "title": "User Sign-Up", "description": "New user creates an account...", "userGoal": "Create a new account to access...", "actions": [ "Navigate to authentication page", "Click 'Sign Up' tab or button", // ... ], "expectedOutcome": "User is authenticated and redirected...", "testData": { "firstName": "John", "lastName": "Tester", "email": "test-{timestamp}@example.com", "password": "TestPassword123!" }, "validations": [ "User is redirected to /home route", "Navigation bar shows user is authenticated", // ... ] }

Template Placeholders

Test data may contain template placeholders like {timestamp} that should be replaced with actual values:

// Journey data: "test-{timestamp}@example.com" // In test: `test-${Date.now()}-${randomString}@example.com`

🎯 Benefits

For Developers
  • Understand user workflows quickly
  • Reference standardized test data
  • Ensure tests match documented behavior
For Testers
  • Clear step-by-step test cases
  • Expected outcomes defined
  • Validation criteria specified
For Stakeholders
  • Visual representation of user flows
  • Understand different user personas
  • See complete feature coverage
For Maintenance
  • Single source of truth
  • Update once, affect docs and tests
  • Prevent documentation drift

🔄 Updating Journey Documentation

When user workflows change:

  1. Update JSON - Edit docs/user-journey.json with new steps or data
  2. Update Markdown - Update docs/user-journeys.md if needed
  3. Update HTML - Update docs/user-journeys.html if visual changes needed
  4. Test Changes - Verify tests still work with updated data
  5. Commit Together - Keep documentation and code in sync

🛠️ Configuration

Environment Variables

# Override default journey data path export USER_JOURNEY_PATH="/custom/path/to/user-journey.json"

Caching

The helper caches journey data after first load for performance. To clear cache during development, restart your test process.

🎓 Learning Path

1. New to the project?

2. Writing E2E tests?

3. Updating workflows?

💡 Tips

❓ FAQ

Q: Can I add custom test data for specific test scenarios?

A: Yes! Use journey data as a baseline, then extend or override for specific test cases.

Q: Should I update tests when journey data changes?

A: Most tests should adapt automatically. Review tests that rely on specific data structures.

Q: Can journey data include sensitive information?

A: No! Journey data is committed to the repository. Use placeholders and generate sensitive data dynamically in tests.

Q: What if my test needs data not in the journey?

A: Add it to the journey if it's standard test data, or generate it dynamically if it's test-specific.

Version: 1.0.0

Last Updated: November 22, 2024

Maintained By: Development Team

↑