Proposal: Restructure Test Handbook to Support Multiple Testing Domains

[huzaifaalmesbah]

Objective

Restructure the Test Handbook to consolidate testing documentation, improve onboarding, and accommodate the expanding scope of the Test Team (Core, Gutenberg, Performance, AI).

The Problem

Currently, the testing documentation is fragmented and Core-centric:

• Split Documentation: The Test Handbook only covers Playground testing. Critical guides like "Set up a local environment" and "Grunt testing" still appear to live in the Core Handbook, creating a disjointed experience.
• Outdated Content: Existing Core testing docs are often outdated or not optimized for testers.
• Confusion: New contributors struggle to navigate between handbooks, leading to a poor onboarding experience.
• Scalability: A flat structure cannot support new domains like AI or Performance without clutter.

Proposed Solution

We propose an Incremental & Project-Based Approach to migration.

1. Consolidate Core Docs: Immediately move/create "Set up a Local Environment" and "Test with Grunt" guides into the Test Handbook to reduce reliance on the Core Handbook.
2. Adopt a Project-Based Hierarchy: Group documentation by domain to keep things organized.

New Directory Structure

We will restructure get-setup-for-testing/ into dedicated project folders:

test-handbook/
├── get-setup-for-testing/
│   │
│   ├── index.md                  # Main Landing Page
│   │
│   ├── core/                  # WordPress Core Testing
│   │   ├── index.md
│   │   ├── set-up-a-testing-environment.md   # [NEW] Local env options (Docker, Lamp, Valet, Herd, Laragon etc)
│   │   ├── test-core-tickets-with-grunt.md   # [NEW] Grunt workflows
│   │   ├── test-core-tickets-with-playground.md
│   │   └── run-automated-tests.md
│   │
│   ├── gutenberg/             # Gutenberg / Block Editor
│   │   └── index.md
│   │
│   ├── performance/           # Performance Team
│   │   └── index.md
│   │
│   └── ai/                    # AI
│       └── index.md

New Handbook Menu (Manifest)

The sidebar navigation will reflect this logical grouping:

• Get Setup for Testing
  • WordPress Core
    • Set Up a Local Environment
    • Test Core Tickets with Playground
    • Test Core Tickets with Grunt
    • Run Automated Tests
  • Gutenberg
  • Performance
  • AI

---

Benefits

1. Unified Onboarding: One central place for all testing needs, eliminating the need to jump to the Core Handbook.
2. Practical & Scoped: Focuses on immediate needs (Local Env, Grunt) while paving the way for future sections.
3. Future-Proof: Ready for new testing initiatives without cluttering the main menu.
4. Clear Ownership: Shifts documentation maintenance closer to the Test Team.

[juanmaguitar]

As I mentioned in today's Test Team Chat, I would try to avoid having duplicated information. Whenever possible I would link to resources on other handbooks or open conversations with other teams to consolidate info in one place.

[huzaifaalmesbah]

Proposal New Directory Structure

get-setup-for-testing/
│
├── index.md                  # Main Landing Page (Hub)
│
├── core/                     # WordPress Core Testing
│   ├── index.md              # Core overview page
│   ├── set-up-a-testing-environment.md
│   ├── test-core-tickets-with-grunt.md
│   ├── test-core-tickets-with-playground.md
│   └── run-automated-tests.md

Proposal New Handbook Links

get-setup-for-testing/
│
├── https://make.wordpress.org/test/handbook/get-setup-for-testing/  (Main Landing Page (Hub))
│
├── core/
│   ├── https://make.wordpress.org/test/handbook/get-setup-for-testing/core/
│   ├── https://make.wordpress.org/test/handbook/get-setup-for-testing/core/set-up-a-testing-environment/
│   ├── https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-grunt/
│   ├── https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-playground/
│   └── https://make.wordpress.org/test/handbook/get-setup-for-testing/core/run-automated-tests/

Current Directory Structure

get-setup-for-testing/
│
├── index.md                  # Main Landing Page
│
├── set-up-a-testing-environment.md
│
├── test-core-tickets-with-playground.md
│
├── test-core-tickets-with-grunt.md
│
└── run-automated-tests.md

Current Handbook Links

get-setup-for-testing/
│
├── https://make.wordpress.org/test/handbook/get-setup-for-testing/  (Main Landing Page)
│
├── https://make.wordpress.org/test/handbook/get-setup-for-testing/set-up-a-testing-environment/
│
├── https://make.wordpress.org/test/handbook/get-setup-for-testing/test-core-tickets-with-playground/
│
├── https://make.wordpress.org/test/handbook/get-setup-for-testing/test-core-tickets-with-grunt/
│
└── https://make.wordpress.org/test/handbook/get-setup-for-testing/run-automated-tests/

[huzaifaalmesbah]

Main Landing Page (Hub) For Get Setup for Testing

Note: This is a proposed content structure. It can be expanded and improved further during implementation.

# Get Set Up for Testing

Welcome to the WordPress Test Team! This section covers how to set up environments for testing different WordPress projects.

## WordPress Core

Test WordPress core tickets, patches, and releases.
- [Set up a local testing environment](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/set-up-a-testing-environment/)
- [Test with Playground (browser-based)](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-playground/)
- [Test with Grunt (local patches)](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-grunt/)
- [Run automated tests](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/run-automated-tests/)

## Gutenberg

*Coming soon*

## Performance

*Coming soon*

## AI

*Coming soon*

## Quick Start

New to testing? Start here:

1. **Quick visual testing** → Use [WordPress Playground](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-playground/) (no installation needed)
2. **Patch testing** → [Set up a local environment](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/set-up-a-testing-environment/)
3. **Contribute patches** → [Test with Grunt](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-grunt/)

Core overview page (Core Landing Page)

Note: This is a proposed content structure. It can be expanded and improved further during implementation.

# WordPress Core Testing

Test WordPress core tickets, patches, and releases. Core testing helps ensure WordPress remains stable and bug-free.

## Testing Methods

| Method | Best For | Requirements |
|--------|----------|--------------|
| [Playground](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-playground/) | Quick visual testing, PR verification | Browser only |
| [Local + Grunt](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-grunt/) | Patch testing, complex features | Local environment |
| [Automated Tests](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/run-automated-tests/) | Regression testing, patch validation | Local environment |

## Getting Started

### Option 1: Browser-Based (Easiest)
Test pull requests directly in your browser using WordPress Playground. No installation required.

→ [Test Core Tickets with Playground](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/test-core-tickets-with-playground/)

### Option 2: Local Environment
Set up a local development environment for more advanced testing, running automated tests, and working with patches.

→ [Set Up a Local Testing Environment](https://make.wordpress.org/test/handbook/get-setup-for-testing/core/set-up-a-testing-environment/)

## Prerequisites

Before testing core tickets, familiarize yourself with:
- [Trac Ticket System](https://core.trac.wordpress.org/) - Where WordPress core bugs are tracked
- [GitHub Pull Requests](https://github.com/WordPress/wordpress-develop/pulls) - Where patches are submitted
- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) - Helpful for understanding code changes