Reconnexion/festipod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Sylvain Duchesne
2026-01-18 11:53:42 +01:00
commit f04f15d926
112 changed files with 24858 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+50
View File
@@ -0,0 +1,50 @@
# Festipod Documentation
This documentation is split into three parts:
## 1. [Festipod Mobile App](./festipod-app.md)
The mobile application being designed - an event discovery and networking platform. This section covers:
- App concept and target users
- User stories (26 stories across 5 categories)
- Screen mockups (13 screens)
- Feature specifications (Cucumber/Gherkin)
## 2. [Prototyping Tool](./prototyping-tool.md)
The web application built to visualize and document the Festipod project. This section covers:
- Architecture and navigation
- Gallery, Demo, Stories, and Specs pages
- Component library (Sketchy UI)
- Build and development setup
## 3. [Cucumber Integration](./cucumber-integration.md)
Technical documentation for the BDD testing framework. This section covers:
- Test architecture and configuration
- World class and state management
- Step definitions (navigation, form, screen)
- Running tests and generating reports
---
## Quick Start
```bash
# Install dependencies
bun install
# Start development server
bun run dev
# Run Cucumber tests
bun run test:cucumber
# Parse feature files
bun run features:parse
```
Open http://localhost:3000 to view the prototyping tool.
docs/cucumber-integration.md
+328
View File
@@ -0,0 +1,328 @@
# Cucumber BDD Integration
This document explains how the Cucumber BDD testing framework is integrated into Festipod.
## Overview
Festipod uses **Cucumber.js** with **TypeScript** for Behavior-Driven Development testing. All feature files are written in **French** using Gherkin syntax. The integration uses static source code analysis rather than browser automation.
## Architecture
```
Feature Files (French Gherkin)
↓
Cucumber Parser (language: "fr")
↓
Step Definition Matching
↓
World Instance (FestipodWorld)
↓
Screen Source Analysis (regex field detectors)
↓
Chai Assertions
↓
JSON + HTML Reports
```
## Directory Structure
```
features/
├── support/
│ ├── world.ts # Custom World class with state management
│ └── hooks.ts # Before/After lifecycle hooks
├── step_definitions/
│ ├── navigation.steps.ts # Screen navigation steps
│ ├── form.steps.ts # Form validation steps
│ └── screen.steps.ts # Content verification steps
├── user/ # User-related features (9 files)
├── event/ # Event features (5 files)
├── workshop/ # Workshop features (6 files)
├── meeting/ # Meeting features (1 file)
└── notif/ # Notification features (3 files)
```
## Configuration
The `cucumber.json` file configures the test runner:
```json
{
"default": {
"import": [
"features/support/**/*.ts",
"features/step_definitions/**/*.ts"
],
"paths": ["features/**/*.feature"],
"format": [
"progress-bar",
"json:reports/cucumber-report.json",
"html:reports/cucumber-report.html"
],
"language": "fr",
"formatOptions": {
"snippetInterface": "async-await"
},
"strict": false
}
}
```
- **language: "fr"** - Uses French Gherkin keywords (Fonctionnalité, Scénario, Étant donné, Quand, Alors)
- **strict: false** - Allows pending scenarios to be reported without failing the test suite
- **Reports** - Generates both JSON (for CI) and HTML (human-readable) reports
## World Class
The `FestipodWorld` class (`features/support/world.ts`) maintains test state:
### Tracked State
| Property | Type | Description |
|----------|------|-------------|
| `currentRoute` | `string` | Current URL hash (e.g., `#/demo/home`) |
| `currentScreenId` | `string` | Current screen identifier |
| `formFields` | `Map` | Form fields with required flag and value |
| `navigationHistory` | `string[]` | All visited routes |
| `isAuthenticated` | `boolean` | Login state |
| `screenSourceContent` | `string` | Raw TypeScript source of current screen |
### Key Methods
- `navigateTo(route)` - Navigate to a screen, load its source code
- `hasField(fieldName)` - Check if a semantic field exists using regex detectors
- `hasText(text)` - Check if text exists in screen source
- `hasElement(selector)` - Check for JSX elements
- `getRenderedText()` - Get the full source code for matching
### Screen Name Mapping
French screen names are mapped to screen IDs:
```typescript
screenNameMap = {
'accueil': 'home',
'créer un événement': 'create-event',
'détail événement': 'event-detail',
'mon profil': 'profile',
'profil utilisateur': 'user-profile',
// ... etc
}
```
### Screen-Specific Field Detectors
Field detection is screen-specific, defined in `screenFieldDetectors` map. Each screen has its own set of regex patterns to identify UI elements:
**event-detail screen:**
| Field | Detection Pattern |
|-------|-------------------|
| Titre | `<Title>content</Title>` |
| Date | 📅 emoji + French month name + year |
| Heure | 🕓 emoji + time pattern (e.g., 14h30) |
| Lieu | 📍 emoji + capitalized location name |
| Description | "À propos" section with 50+ chars of text |
| Photo | `<Avatar` component |
**user-profile / profile screens:**
| Field | Detection Pattern |
|-------|-------------------|
| Nom | `<Title>` with capitalized first/last name |
| Pseudo | `@username` pattern |
| Photo / Photo de profil | `<Avatar` component |
This approach makes tests resilient to minor UI changes while still validating the semantic structure of screens.
## Step Definitions
### Navigation Steps (`navigation.steps.ts`)
```gherkin
# Given steps
Étant donné je suis sur la page "accueil"
Étant donné je suis connecté(e)
# When steps
Quand je navigue vers "détail événement"
Quand je clique sur {string}
Quand je clique sur un participant
# Then steps
Alors je suis redirigé vers "profil utilisateur"
Alors je vois l'écran "profile"
Alors l'écran contient une section "Photo de profil"
```
### Form Steps (`form.steps.ts`)
```gherkin
# Validating required fields
Alors le formulaire contient le champ obligatoire "Titre"
# Multiple fields with DataTable
Alors le formulaire contient les champs obligatoires suivants:
| Titre |
| Date |
| Description |
# Form interaction
Quand je remplis le champ "Titre" avec "Mon événement"
Quand je laisse le champ "Date" vide
Alors une erreur de validation est affichée pour "Date"
```
### Screen Steps (`screen.steps.ts`)
```gherkin
# Content verification
Alors je peux voir la liste des participants
Alors l'écran affiche les informations de l'événement
# Feature detection (returns 'pending' if not implemented)
Alors je peux ajouter un commentaire
Alors je peux ajouter une note
Alors je peux modifier un commentaire
Alors je peux supprimer un commentaire
Alors je peux m'inscrire à l'événement
Alors je peux voir le QR code
Alors je peux filtrer les événements par période
```
## Hooks
Lifecycle hooks in `features/support/hooks.ts`:
| Hook | Purpose |
|------|---------|
| `BeforeAll` | Log test suite start |
| `Before` | Reset World state, mark `@pending` scenarios as pending |
| `After` | Attach debug info on failure, cleanup |
| `AfterAll` | Log test suite completion |
### Pending Scenarios
Scenarios tagged with `@pending` are automatically marked as pending in the Before hook:
```typescript
Before(async function (this: FestipodWorld, scenario) {
// ... reset state ...
const isPending = scenario.pickle.tags.some(tag => tag.name === '@pending');
if (isPending) {
return 'pending';
}
});
```
Use `@pending` for:
- Features not yet implemented
- Email/notification features that cannot be tested via screen analysis
- Scenarios waiting for UI implementation
### Debug Information on Failure
When a scenario fails, the `After` hook attaches:
- Current route
- Current screen ID
- Navigation history
- Form fields state
- Screen source snippet (first 500 chars)
## Running Tests
```bash
# Run all tests end-to-end (runs tests + generates internal report)
bun run test:cucumber
# Sub-commands for individual steps:
bun run cucumber:run # Only run cucumber tests (generates HTML/JSON reports)
bun run cucumber:report # Only parse results to generate internal report
# Run by category tag
bun run cucumber:run --tags "@USER"
bun run cucumber:run --tags "@EVENT"
bun run cucumber:run --tags "@NOTIF"
# Run by priority
bun run cucumber:run --tags "@priority-0"
# Exclude pending tests
bun run cucumber:run --tags "not @pending"
```
## Parsing Results
After running tests, parse results for the UI:
```bash
# Generate testResults.ts from cucumber-report.json (included in test:cucumber)
bun run cucumber:report
# Regenerate step definitions data
bun run steps:extract
# Parse feature files for UI display
bun run features:parse
```
## Example Feature File
```gherkin
# language: fr
@USER @priority-0
Fonctionnalité: US-9 Visualiser la photo d'un individu
En tant qu'utilisateur
Je peux visualiser la photo d'un individu
Contexte:
Étant donné je suis connecté en tant qu'utilisateur
Scénario: Accéder au profil pour voir la photo
Étant donné je suis sur la page "mon profil"
Alors je vois l'écran "profile"
Et l'écran contient une section "Photo de profil"
Scénario: Naviguer vers le profil depuis la liste des participants
Étant donné je suis sur la page "détail événement"
Quand je clique sur un participant
Alors je suis redirigé vers "profil utilisateur"
@pending
Scénario: Fonctionnalité non encore implémentée
Étant donné je suis sur la page "mon profil"
Alors je peux modifier ma photo de profil
```
## Key Design Decisions
### Static Source Analysis
Instead of running the app in a browser, tests analyze TypeScript source files directly. This approach:
- Runs faster (no browser startup)
- Doesn't require a running server
- Validates code structure, not runtime behavior
### French-First
All Gherkin keywords and step definitions use French:
- `Fonctionnalité` instead of `Feature`
- `Scénario` instead of `Scenario`
- `Étant donné` instead of `Given`
- `Quand` instead of `When`
- `Alors` instead of `Then`
### Semantic Field Detection
Rather than checking for specific CSS selectors or test IDs, the integration uses semantic patterns to detect features. For example, detecting a "Date" field by looking for the 📅 emoji pattern makes tests resilient to UI changes.
## UI Integration
The Specs page (`#/specs`) displays feature files with:
- Collapsible scenarios (failed ones open by default)
- Test status indicators (pass/fail/skip)
- Error messages for failed tests
- Step definition source code tooltips (click "Définitions" button)
Data is generated by build-time scripts:
- `src/data/features.ts` - Parsed feature file content
- `src/data/testResults.ts` - Test execution results
- `src/data/stepDefinitions.ts` - Step definition source code
docs/festipod-app.md
+172
View File
@@ -0,0 +1,172 @@
# Festipod Mobile App
Festipod is a mobile application for discovering, organizing, and attending events. It emphasizes community building and networking through shared activities.
## Concept
The app helps users:
- Discover nearby events and festivals
- Organize their own events with workshops
- Connect with other participants before and during events
- Build a network of contacts with shared interests
## User Stories
26 user stories organized by category and priority.
### Priority Levels
| Priority | Label | Description |
|----------|-------|-------------|
| P0 | Impossible | Not feasible or out of scope |
| P1 | Haute | Core features, must-have |
| P2 | Moyenne | Important features |
| P3 | Basse | Nice-to-have features |
### Categories
| Category | Color | Stories |
|----------|-------|---------|
| EVENT | Blue | Event creation and management |
| WORKSHOP | Green | Workshop scheduling within events |
| USER | Purple | User profiles and networking |
| MEETING | Orange | Meeting points and connections |
| NOTIF | Pink | Notifications and alerts |
### Stories by Priority
#### P1 - Haute (8 stories)
| ID | Category | Title |
|----|----------|-------|
| US-3 | EVENT | Consulter les evenements termines |
| US-7 | EVENT | S'inscrire ou se desinscrire d'un evenement |
| US-10 | USER | Consulter le profil et les coordonnees des participants |
| US-13 | EVENT | Creer, modifier ou supprimer un evenement |
| US-15 | USER | Consulter la liste des participants |
| US-16 | MEETING | Indiquer les points de rencontres |
| US-20 | USER | Consulter la liste des contacts et profils publics |
| US-23 | USER | Se connecter avec un autre utilisateur |
#### P2 - Moyenne (9 stories)
| ID | Category | Title |
|----|----------|-------|
| US-12 | USER | Consulter la carte ou le tableau des evenements |
| US-17 | NOTIF | Recevoir des notifications d'evenements |
| US-18 | NOTIF | Etre notifie des nouveaux inscrits |
| US-19 | NOTIF | Recevoir un recap des evenements |
| US-21 | USER | Rendre son profil public |
| US-22 | USER | Parrainer un nouvel utilisateur |
| US-24 | NOTIF | Etre notifie quand un contact participe |
| US-25 | NOTIF | Recevoir des alertes d'evenements proches |
| US-26 | USER | Definir le rayon de notification |
#### P3 - Basse (8 stories)
| ID | Category | Title |
|----|----------|-------|
| US-1 | WORKSHOP | Consulter les evenements termines avec programme |
| US-2 | WORKSHOP | Ajouter des notes et ressources aux ateliers |
| US-4 | WORKSHOP | Ajouter des commentaires aux ateliers |
| US-6 | WORKSHOP | S'inscrire aux ateliers |
| US-8 | EVENT | Creer un macro-evenement |
| US-11 | WORKSHOP | Consulter le resume consolide |
| US-14 | WORKSHOP | Creer des ateliers dans un evenement |
#### P0 - Impossible (1 story)
| ID | Category | Title |
|----|----------|-------|
| US-9 | USER | Visualiser les photos des utilisateurs |
## Screens
13 mockup screens organized by section.
### Home
| Screen ID | Name | Description |
|-----------|------|-------------|
| home | Accueil | Dashboard with upcoming events |
### Events
| Screen ID | Name | Description |
|-----------|------|-------------|
| events | Decouvrir | Browse available events |
| event-detail | Detail evenement | Full event details and participants |
| create-event | Creer un evenement | Event creation form |
| invite | Inviter | Share event with friends |
| participants-list | Liste participants | Full participants list |
| meeting-points | Points de rencontre | Set/view meeting points |
### User
| Screen ID | Name | Description |
|-----------|------|-------------|
| profile | Mon profil | Current user profile |
| user-profile | Profil utilisateur | View other user's profile |
| friends-list | Mon reseau | Friends and public profiles |
| share-profile | Partager profil | Share profile via QR/link |
### General
| Screen ID | Name | Description |
|-----------|------|-------------|
| login | Connexion | Login screen |
| settings | Parametres | App settings and notifications |
## Screen-Story Mapping
Each screen is linked to one or more user stories:
| Screen | Linked Stories |
|--------|----------------|
| home | US-19 |
| events | US-3, US-25 |
| event-detail | US-7, US-10, US-15, US-16 |
| create-event | US-13 |
| participants-list | US-15 |
| meeting-points | US-16 |
| profile | US-21, US-22 |
| user-profile | US-10, US-20 |
| friends-list | US-20 |
| share-profile | US-22, US-23 |
| settings | US-17, US-24, US-25, US-26 |
## Feature Specifications
BDD specifications written in Gherkin (French) are located in `features/`:
```
features/
event/ # 5 feature files
workshop/ # 6 feature files
user/ # 11 feature files
meeting/ # 1 feature file
notif/ # 3 feature files
```
Each feature file maps to a user story (e.g., `us-13-creer-evenement.feature` for US-13).
### Gherkin Keywords (French)
| French | English | Purpose |
|--------|---------|---------|
| Fonctionnalite | Feature | Feature title |
| Contexte | Background | Shared preconditions |
| Scenario | Scenario | Test case |
| Etant donne | Given | Initial state |
| Quand | When | Action |
| Alors | Then | Expected result |
| Et | And | Additional step |
## Design Language
The mockups use a "Sketchy" design aesthetic:
- Hand-drawn borders and rounded corners
- Informal, prototype-style appearance
- Comic Sans-inspired typography
- Mobile-first (375x812 phone dimensions)
- Bottom navigation bar with icons
docs/prototyping-tool.md
+273
View File
@@ -0,0 +1,273 @@
# Prototyping Tool
A web application for visualizing and documenting the Festipod mobile app project. It combines interactive mockups, user story management, and BDD test integration.
## Overview
The tool provides four main views:
| Page | Route | Purpose |
|------|-------|---------|
| Gallery | `#/` | Browse all mockup screens |
| Stories | `#/stories` | View and filter user stories |
| Demo | `#/demo/{screenId}` | Interactive screen preview |
| Specs | `#/specs` | BDD specifications with test status |
## Architecture
```
src/
App.tsx # Main app with routing
router.tsx # Hash-based SPA router
components/
Gallery.tsx # Screen gallery grid
DemoMode.tsx # Interactive demo view
UserStoriesPage.tsx # Stories listing
sketchy/ # UI component library
specs/ # Specs viewer components
ui/ # Shadcn/Radix components
screens/ # Mockup screen components
data/ # Stories, features, test data
types/ # TypeScript definitions
```
## Pages
### Gallery
The landing page displaying all mockup screens organized by category:
- **Accueil** - Home section
- **Evenements** - Event-related screens
- **Utilisateur** - User profile screens
- **General** - Login, settings
Features:
- Horizontal scrolling layout
- Zoom slider (32% to 75%)
- Click any screen to open in Demo mode
- Navigation buttons to Stories and Specs pages
### Demo Mode
Two-panel interactive preview:
**Left Sidebar:**
- Back to Gallery button
- Current screen with navigation history
- Linked user stories for the screen
- Quick navigation to all screens
**Right Panel:**
- Phone frame with live mockup
- Auto-scales to fit viewport
- Interactive navigation within mockups
Clicking a user story navigates to the Stories page with that story selected.
### Stories Page
User story browser with filtering:
**Filters:**
- Category (EVENT, WORKSHOP, USER, MEETING, NOTIF)
- Priority (P0-P3)
- Linked screen
**Display:**
- Stories grouped by priority
- Color-coded category and priority badges
- Description and linked screens
- Click title to open linked screen in Demo
### Specs Page
BDD specification viewer with test integration:
**Header:**
- Test summary (passed/failed/skipped counts)
- Last run timestamp
- Link to HTML Cucumber report
**Filters:**
- Category checkboxes
- Priority selection
- Text search
**Feature Cards:**
- Feature name and description
- Scenario count
- Test status indicator
- Click to open detailed view
### Feature View
Detailed specification page:
- Priority and category badges
- Clickable user story link
- Linked screens as buttons
- Gherkin syntax highlighting with:
- Collapsible scenarios
- Color-coded keywords
- Step definition tooltips
- Test status indicators
- Error messages for failed scenarios
## Component Library
### Sketchy Components
Hand-drawn style UI components in `components/sketchy/`:
| Component | Purpose |
|-----------|---------|
| PhoneFrame | iPhone-style device frame |
| Header | App header with title and actions |
| NavBar | Bottom navigation with icons |
| Button | Primary and default variants |
| Card | Content container |
| Avatar | User avatar with initials |
| Badge | Label badges |
| Input | Text input field |
| Text | Styled typography |
| Title | Heading text |
| Placeholder | Empty state box |
| Divider | Visual separator |
| Checkbox | Form checkbox |
| Toggle | On/off switch |
| ListItem | List row |
### UI Components
Modern components from Shadcn/Radix in `components/ui/`:
- Button, Card, Badge
- Slider, Input
- Tooltip
- Dialog
## Data Layer
### Stories (`data/index.ts`)
```typescript
interface UserStoryDefinition {
id: string;
priority: number;
category: StoryCategory;
title: string;
description: string;
screenIds: string[];
}
```
Functions:
- `getStoryById(id)` - Get story by ID
- `getStoriesForScreen(screenId)` - Stories linked to a screen
- `getStoriesByCategory(category)` - Filter by category
- `getStoriesByPriority(priority)` - Filter by priority
### Features (`data/features.ts`)
Auto-generated from Cucumber feature files:
```typescript
interface ParsedFeature {
id: string;
name: string;
description: string;
tags: string[];
category: string;
priority: number;
scenarios: ParsedScenario[];
filePath: string;
rawContent: string;
}
```
### Test Results (`data/testResults.ts`)
Parsed from Cucumber JSON reports:
```typescript
interface TestStatus {
passed: number;
failed: number;
skipped: number;
total: number;
}
```
### Step Definitions (`data/stepDefinitions.ts`)
Extracted step implementations for tooltip display.
## Build Scripts
Located in `scripts/`:
| Script | Command | Purpose |
|--------|---------|---------|
| parse-features.ts | `bun run features:parse` | Parse .feature files |
| parse-test-results.ts | `bun run test:report` | Generate test report |
| extract-step-definitions.ts | `bun run steps:extract` | Extract step code |
## Development
### Setup
```bash
bun install
```
### Development Server
```bash
bun run dev
```
Starts server on http://localhost:3000 with HMR.
### Run Tests
```bash
bun run test:cucumber
```
Runs Cucumber tests and generates HTML report.
### Regenerate Data
```bash
# After modifying .feature files
bun run features:parse
# After modifying step definitions
bun run steps:extract
```
## Tech Stack
| Technology | Purpose |
|------------|---------|
| Bun | Runtime and bundler |
| React 19 | UI framework |
| TypeScript | Type safety |
| Tailwind CSS | Utility styling |
| Radix UI | Accessible primitives |
| Lucide | Icons |
| Cucumber | BDD testing |
## Future Plans
This prototyping tool is designed to be extracted as a standalone application for:
- Rapid mobile app prototyping
- User story management
- BDD specification writing
- Test result visualization
The "Sketchy" design system emphasizes the prototype nature and can be swapped for production-ready components.