# Pillar Pages in Related Posts - Testing Guide

**Last Updated:** 2026-01-19

Complete guide for testing that pillar pages appear correctly in the related posts carousel on blog post pages.

## Overview

Pillar pages are integrated into blog posts' `related_posts` arrays and should appear in the "Ähnliche Artikel" (Related Posts) carousel on blog post pages. This document outlines both automated and manual testing procedures.

## Automated Testing

### Test Script

Run the automated test script to verify pillar pages are loaded correctly:

```bash
# Test all posts with pillar pages
php v2/scripts/blog/test-pillar-related-posts.php --all

# Test a specific post
php v2/scripts/blog/test-pillar-related-posts.php --post=slug --category=category
```

### What the Script Tests

1. **Pillar Page Loading**: Verifies that `load_pillar_page_data()` function correctly loads pillar page metadata
2. **Related Posts Integration**: Confirms pillar pages appear in `load_related_posts_enhanced()` results
3. **Data Structure**: Validates that pillar pages have correct structure (title, URL, category, excerpt, etc.)
4. **Category Label**: Checks that pillar pages display with correct category label ("Umfassender Guide")

### Expected Results

All 8 posts with pillar pages should pass:
- ✅ `ratgeber/dienstplan-gesetz` - Both dienstplan and zeiterfassung pillars
- ✅ `ratgeber/arbeitsstunden-pro-monat` - Zeiterfassung pillar
- ✅ `lexikon/24-stunden-schicht` - Dienstplan pillar
- ✅ `lexikon/feiertagsausgleich` - Zeiterfassung pillar
- ✅ `ratgeber/gastronomie-mindestlohn` - Zeiterfassung pillar
- ✅ `ratgeber/dienstplan-erstellen` - Dienstplan pillar
- ✅ `ratgeber/urlaubsantrag-stellen` - Both dienstplan and zeiterfassung pillars
- ✅ `lexikon/industrieminuten` - Zeiterfassung pillar

## Manual Visual Testing

### Prerequisites

1. **Local Development Server**: Blog posts should be accessible via local server (e.g., `http://localhost:8003`)
2. **Browser DevTools**: Open browser developer tools to inspect HTML and network requests
3. **Test Posts List**: Use the list above to test specific posts

### Visual Verification Checklist

For each blog post that should have pillar pages:

#### 1. Page Load Test

- [ ] Navigate to blog post URL (e.g., `/insights/ratgeber/dienstplan-gesetz/`)
- [ ] Page loads without errors
- [ ] Related posts section appears below main content

#### 2. Pillar Page Display Test

- [ ] Pillar page card appears in related posts carousel
- [ ] Card displays correct title (e.g., "Dienstplan 2026: Definition, Erstellung & Software - Ordio")
- [ ] Card displays correct category badge ("Umfassender Guide")
- [ ] Card displays correct excerpt/description
- [ ] Card displays featured image (if available)
- [ ] Card link points to correct pillar page URL (e.g., `/insights/dienstplan/`)

#### 3. PostCard Component Test

- [ ] Pillar page card uses same styling as regular blog post cards
- [ ] Card is responsive (test on mobile, tablet, desktop)
- [ ] Card hover effects work correctly
- [ ] Card click navigates to pillar page correctly

#### 4. Multiple Pillar Pages Test

For posts with multiple pillar pages (e.g., `dienstplan-gesetz`, `urlaubsantrag-stellen`):

- [ ] Both pillar pages appear in carousel
- [ ] Both cards display correctly
- [ ] Cards are positioned appropriately (usually in top 3-5 positions)

#### 5. Browser Console Test

- [ ] Open browser DevTools Console
- [ ] Check for JavaScript errors
- [ ] Verify no 404 errors for pillar page images
- [ ] Check network tab for successful pillar page loads

### Test URLs

**Posts with Dienstplan Pillar:**
- `/insights/ratgeber/dienstplan-gesetz/`
- `/insights/lexikon/24-stunden-schicht/`
- `/insights/ratgeber/dienstplan-erstellen/`
- `/insights/ratgeber/urlaubsantrag-stellen/`

**Posts with Zeiterfassung Pillar:**
- `/insights/ratgeber/dienstplan-gesetz/`
- `/insights/ratgeber/arbeitsstunden-pro-monat/`
- `/insights/lexikon/feiertagsausgleich/`
- `/insights/ratgeber/gastronomie-mindestlohn/`
- `/insights/ratgeber/urlaubsantrag-stellen/`
- `/insights/lexikon/industrieminuten/`

## Technical Implementation

### Function: `load_pillar_page_data()`

Located in `v2/config/blog-template-helpers.php`, this function:

1. Returns pillar page metadata in the same format as blog posts
2. Supports caching for performance
3. Currently supports two pillar pages:
   - `dienstplan`
   - `zeiterfassung`

### Function: `load_related_posts_enhanced()`

Updated to handle pillar pages:

1. Checks if `related_category === 'pillar'`
2. Calls `load_pillar_page_data()` instead of `load_blog_post()`
3. Returns pillar page data in same format as blog posts

### Category Label: `get_category_label()`

Updated to return "Umfassender Guide" for `category === 'pillar'`.

## Troubleshooting

### Pillar Page Not Appearing

1. **Check JSON File**: Verify `related_posts` array includes pillar page entry:
   ```json
   {
     "slug": "dienstplan",
     "category": "pillar",
     "similarity_score": 0.9,
     "relationship_type": "pillar_page"
   }
   ```

2. **Check Function**: Verify `load_pillar_page_data()` function exists and is called correctly

3. **Check Cache**: Clear PHP opcache if using opcache:
   ```bash
   php -r "opcache_reset();"
   ```

### Pillar Page Appears But Wrong Data

1. **Check Metadata**: Verify pillar page metadata in `load_pillar_page_data()` function
2. **Check URL**: Ensure pillar page URL is correct (e.g., `/insights/dienstplan/`)
3. **Check Images**: Verify featured image paths exist

### Category Badge Not Displaying

1. **Check Function**: Verify `get_category_label('pillar')` returns "Umfassender Guide"
2. **Check PostCard**: Verify PostCard component uses `get_category_label()` function

## Related Documentation

- `docs/content/blog/PILLAR_PAGE_INTEGRATION_CHECKLIST.md` - Integration checklist
- `docs/content/blog/TIER1_PILLAR_MAPPING.md` - Pillar page mapping
- `v2/scripts/blog/validate-pillar-links.php` - Validation script
- `v2/scripts/blog/test-pillar-related-posts.php` - Automated test script

## Summary

✅ **Automated Testing**: All 8 posts pass automated tests
✅ **Function Implementation**: `load_pillar_page_data()` implemented and working
✅ **Category Label**: "Umfassender Guide" label added for pillar pages
✅ **Related Posts Integration**: Pillar pages correctly integrated into related posts carousel

**Next Steps**: Perform manual visual testing on live/staging environment to verify UI/UX.