Skip to content

Proposal: Restructure Test Handbook to Support Multiple Testing Domains #111

Description

@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.

Activity

  1. juanmaguitar commented on Feb 12, 2026

    @juanmaguitar
    Collaborator

    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.

  2. huzaifaalmesbah commented on Mar 28, 2026

    @huzaifaalmesbah
    MemberAuthor

    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/
    
    
  3. huzaifaalmesbah commented on Mar 28, 2026

    @huzaifaalmesbah
    MemberAuthor

    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
    
    
  4. Successfulsebunya commented on Jul 2, 2026

    @Successfulsebunya
    Member

    Discussed during the test voice chat and will add comments later

    but in brief
    r1k0

    1. Possibility of Duplication in core and else where
    2. nice proposal for the test handbook

    nikunj

    • Need to create Ai and Performance sections in the current handbook in the test handbook

    ozgursar

    • Asked how we can find the tickets and issues and he seconds the iodea
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions