joomla · mahmoudmagdy1-1 · Aug 12, 2025 · Aug 12, 2025 · Aug 12, 2025
diff --git a/docs/testing/manually/_assets/create-github-codespace.png b/docs/testing/manually/_assets/create-github-codespace.png
diff --git a/docs/testing/manually/_assets/cypress-tests-running.png b/docs/testing/manually/_assets/cypress-tests-running.png
diff --git a/docs/testing/manually/_assets/github-codespaces-ports.png b/docs/testing/manually/_assets/github-codespaces-ports.png
diff --git a/docs/testing/manually/_assets/github-pr-plugin-checkout.png b/docs/testing/manually/_assets/github-pr-plugin-checkout.png
diff --git a/docs/testing/manually/_assets/initial-vscode-setup.png b/docs/testing/manually/_assets/initial-vscode-setup.png
diff --git a/docs/testing/manually/_assets/phpmyadmin-interface.png b/docs/testing/manually/_assets/phpmyadmin-interface.png
diff --git a/docs/testing/manually/github-codespaces.md b/docs/testing/manually/github-codespaces.md
@@ -0,0 +1,70 @@
+---
+sidebar_position: 6
+---
+
+GitHub Codespaces
+=================================
+
+GitHub Codespaces provides a complete, configurable development environment in the cloud for testing Joomla! pull requests, or even using as a dev environment.
+
+## Getting Started
+
+To get started with testing a pull request using GitHub Codespaces, follow these steps:
+
+1.  Navigate to the pull request you want to test on GitHub.
+2.  Click the **Code** button in the top right.
+3.  Select the **Create codespace** option.
+![create github codespace](_assets/create-github-codespace.png)
+4.  A new browser tab will open, and GitHub will begin creating the Codespace. This process will take a few minutes as it sets up the entire Joomla 
+development environment, including installing dependencies and running the Joomla installation script.
+
+## The Codespace Environment
+
+Once the setup is complete, you will be in a Visual Studio Code environment within your browser. A file named `codespace-details.txt` will be available, 
+containing all the necessary credentials to access the Joomla installation.
+
+![vscode initial setup](_assets/initial-vscode-setup.png)
+
+### Accessing Joomla and phpMyAdmin
+
+The `codespace-details.txt` file provides you with:
+
+*   **Joomla Admin Credentials:** Username and password for the administrator account.
+*   **phpMyAdmin Credentials:** Username and password for phpMyAdmin.
+
+To access these, navigate to the **Ports** tab in VS Code. You will find forwarded ports (e.g., "Web Server", "Cypress"). Click the globe icon next to the HTTP(S) forwarded URL for the web server to open the Joomla site in a new tab.
+
+![github-code](_assets/github-codespaces-ports.png)
+
+### Managing the Database with phpMyAdmin
+
+The environment includes phpMyAdmin, which allows you to directly manage the Joomla database. This is useful for verifying data changes,
+importing test data, or debugging issues at the database level.
+
+1.  Find the **phpMyAdmin URL** and **credentials** in the `codespace-details.txt` file.
+2.  Open the URL in your browser to access the phpMyAdmin login page.
+3.  Log in using the provided credentials.
+
+![phpMyAdmin interface with the database tables](_assets/phpmyadmin-interface.png)
+
+### Running Interactive Cypress Tests
+
+The environment is ready for end-to-end testing with Cypress.
+
+1. In the VS Code terminal, run `npx cypress open`.
+2. Navigate to the Ports tab and click the globe icon next to the Cypress GUI port to open the test interface in a new tab.
+
+![cypress-tests-running](_assets/cypress-tests-running.png)
+
+### Testing a Pull Request
+
+The primary benefit of using Codespaces is the ease of testing PRs. The environment is set up with the code from the branch the Codespace was created
+from. To test a different PR:
+
+1.  Use the **GitHub** extension in the VS Code sidebar.
+2.  Find the pull request you want to test.
+3.  Click the **Checkout** button.
+
+The changes from the pull request will be applied to the files, and you can immediately see the effect in your running Joomla instance.
+
+![github plugin pull request checkout](_assets/github-pr-plugin-checkout.png)
diff --git a/docs/testing/manually/index.md b/docs/testing/manually/index.md
@@ -9,6 +9,23 @@ Testers are individuals who know how to use Joomla! and have some time available
 
 ## Testing Environment
 
+To test pull requests, you need a working Joomla! installation. You have two main options for setting up your environment: a fully automated cloud
+environment with GitHub Codespaces, or a traditional local setup on your own computer.
+
+### GitHub Codespaces
+
+The easiest and fastest way to get started with testing is to use GitHub Codespaces. It provides a complete, pre-configured development environment
+that runs directly in your browser.
+
+**Why use Codespaces?**
+- **No Local Setup:** You don't need to install a web server, PHP, a database, or any other tool on your computer.
+- **Fast & Simple:** Your testing environment is ready in just a few minutes with a single click.
+- **Consistent & Reliable:** Everyone uses the same setup, which reduces errors and "it works on my machine" problems.
+
+For a step-by-step guide, please see the **[Testing PRs with GitHub Codespaces](./github-codespaces.md)** documentation.
+
+### Local Environment
+
 To get started you need an environment in which you can easily create multiple Joomla installations. This is because tests are often based on a specific branch, such as 5.2-dev, 5.3-dev or 6.0-dev. You could put different installations in subfolders with names such as jcms-test-52 or jcms-test-60 or whatever. This is a summary of what you need:
 
 - A laptop or desktop computer with a web server, database and PHP installed.