Skip to content

Commit 631ef57

Browse files
Adding QA Guide to DevDocs Guides
Updated links and added details for account setup instructions. Fixed image sizing Update FAQ for QA testing cycle and documentation links Adding badge image Revise QA testing getting started guide Updated instructions for setting up accounts and running tests, clarified steps and links, and improved overall readability. Revise test templates in getting started guide Fixed the rendering of the templates to match the original confluence. It's not perfect, but closest that's possible before changing css of the dropdowns Update QA cycle opening date to 1st September 2026 Change QA cycle opening date to 1st September 2026 Updated the opening date for the Moodle 5.3 QA cycle. Fix link to Getting Started guide in FAQ Updated link to the Getting Started guide in FAQ. Apply suggestions from copilot review Adding QA Guide to DevDocs Co-Authored-By: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent fabb20e commit 631ef57

8 files changed

Lines changed: 357 additions & 0 deletions

File tree

docs/qatesting.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: QA Testing guides
3+
tags:
4+
- Quality Assurance
5+
- Testing
6+
- Core development
7+
---
8+
9+
{/* <!-- markdownlint-disable no-inline-html --> */}
10+
11+
Moodle is used by millions of learners and teachers around the world, and it's supported by a global community of developers, educators, and administrators who care about the platform. Before every major release, that community runs a QA testing cycle: real people using Moodle the way real site administrators, teachers, and students do, checking that new features and fixes actually work. This matters because automated tests can't catch everything; a human trying to complete a real task often finds the rough edges a script never would.
12+
13+
**Do I need to be a developer or a professional tester?** No. Most QA testing is about using Moodle like a teacher would, so you don't need any coding experience.
14+
15+
**How much time do I need for a test?** Testing is flexible and asynchronous. No fixed hours, no minimum commitment, and every test counts. Time depends on how familiar you already are with the area being tested and the number of steps in the test case. As a rough guide, allow 15 minutes for one-time account setup, then 20–40 minutes per test.
16+
17+
**Do I need a Moodle site?** No, we provide a shared QA Moodle site that's already set up and ready to log into, no installation needed.
18+
19+
:::note[Next QA Cycle]
20+
The [Moodle 5.3 QA cycle](https://moodle.atlassian.net/jira/dashboards/10612) opens 1st September 2026.
21+
:::
22+
23+
If you want to understand how to Get Started as a tester, read our [Getting Started](./qatesting/gettingstarted.md) guide
24+
25+
More details about the QA process can be found on our [QA process page](https://moodledev.io/general/development/process/testing/qa).
26+
27+
---
109 KB
Loading
37.3 KB
Loading

docs/qatesting/commonterms.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Common Terms
3+
tags:
4+
- Quality Assurance
5+
- Testing
6+
- Core development
7+
sidebar_position: 2
8+
---
9+
10+
{/* <!-- markdownlint-disable no-inline-html --> */}
11+
12+
New to the jargon? Quick glossary
13+
14+
- **Cycle**: the few weeks before a release when the community works through the test plan together.
15+
- **The Tracker**: Moodle's issue-tracking system (Jira), used to report bugs and test results.
16+
- **Test case / issue**: a single written test, made up of a series of steps and an expected result.
17+
- **Component**: the part of Moodle a test belongs to (e.g. "Book activity", "Quiz"). Useful for filtering tests by topic.
18+
- **MDLQA**: the project prefix for QA test tickets on the Moodle Tracker.
19+
20+
---

docs/qatesting/faq.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Frequently Asked Questions
3+
tags:
4+
- Quality Assurance
5+
- Testing
6+
- Core development
7+
sidebar_position: 3
8+
---
9+
10+
{/* <!-- markdownlint-disable no-inline-html --> */}
11+
12+
## FAQ
13+
14+
<details>
15+
<summary>Do I need to be a developer?</summary>
16+
17+
No. This is one of the most common misconceptions, and a big part of why we're writing this page. Most QA testing is about using Moodle like a normal user would: following a written test case ("log in, create a lesson, add a student") and reporting whether it worked as expected. You're not writing code, and you don't need to know how Moodle is built under the hood.
18+
19+
The only two new things are creating the Moodle Tracker account and reporting your results there instead of in your own notes. Both are learnable in a few minutes, and covered in the [Getting Started](./gettingstarted.md) guide.
20+
21+
</details>
22+
23+
<details>
24+
<summary>How long does it take to do a test?</summary>
25+
26+
Roughly 20 to 40 minutes per test, depending on how many steps it has and how familiar you already are with that part of Moodle. The first time, budget about 15 minutes extra for one-time account setup (covered in "How to start" above).
27+
28+
As mentioned above, testing is flexible and asynchronous. No fixed hours, no minimum commitment. And every test counts.
29+
30+
</details>
31+
32+
<details>
33+
<summary>When does the next QA cycle run?</summary>
34+
35+
The Moodle 5.3 cycle runs from 31 August 2026 to 2 October 2026.
36+
37+
</details>
38+
39+
<details>
40+
<summary>How can I hear about future cycles?</summary>
41+
42+
For future cycles, subscribe to the [Testing and QA forum](https://moodle.org/mod/forum/view.php?id=56), where cycle announcements and any changes get posted.
43+
44+
</details>
45+
46+
<details>
47+
<summary>Why are you promoting testing 5.3 in particular?</summary>
48+
49+
Because 5.3 is special. Roughly every three releases, Moodle designates one as a Long-Term Support (LTS) version. Many organisations skip straight from one LTS release to the next. Moodle 5.3 is one of those releases, so there's a good chance your own institution will upgrade to it before long. Testing 5.3 now is, indirectly, helping your institution, your students, and yourself.
50+
51+
</details>
52+
53+
<details>
54+
<summary>Why do people help test Moodle?</summary>
55+
56+
Moodle testers each have their own reasons for getting involved. For Michelle Lomman, an Instructional Designer and Moodle Educator based in Melbourne: "Moodle has given me so much, so I wanted to be able to contribute something back."
57+
58+
For Al Rachels, a long-time Moodle plugins maintainer and retired Computer Applications teacher in the US, it was "the best way to really understand the new bits and pieces of the next Moodle version."
59+
60+
Source: ["QA testing for Moodle 4.0 – A community effort!"](https://moodle.com/news/qa-testing-moodle-4/) at moodle.com
61+
62+
</details>
63+
64+
<details>
65+
<summary>What do I get out of it?</summary>
66+
67+
Beyond directly improving software used by learners worldwide, your Moodle profile will get a QA tester badge for each cycle you help test. This is the badge from 2025:
68+
69+
import QATestingBadge from './_faq/testingbadge.png';
70+
71+
<center><img src={QATestingBadge} width="200" alt="Moodle QA Testing Badge 2025"/></center>
72+
73+
Also, your name will appear in the [Moodle testing credits page](/general/community/credits/testing) at the end of the QA cycle. It's also a genuinely good, low-pressure way to get comfortable with how a large open-source project runs, and how QA works in software generally, if that's something you're curious about.
74+
75+
</details>
76+
77+
<details>
78+
<summary>I have questions or want to share feedback. How do I get in touch?</summary>
79+
80+
This is our first time reaching out to new testers this way, so if the process trips you up anywhere (you can't assign yourself a test, a step is unclear, you can't create an issue on the Tracker), that's on us to fix, not a sign you're doing something wrong. Telling us what didn't make sense helps us fix the instructions for the next person, not just you. We'd also love to hear how your first time testing went.
81+
82+
Reach us in any of these places:
83+
84+
- The [Testing & QA forum](https://moodle.org/mod/forum/view.php) is actively watched, and a good place to subscribe so you know when a new cycle opens.
85+
- [Moodle QA chat on Matrix](https://matrix.to/#/#qa:moodle.com) is our live chat channel for testers.
86+
- The comments section on the test case itself; useful for questions specific to one test.
87+
88+
If something unrelated to the test itself goes wrong, add the `qa_help_needed` label to the ticket and leave a comment with your question. If the test instructions themselves seem outdated or unclear, add the `qa_instructions_update` label instead — that helps us fix it for the next tester too.
89+
90+
</details>
91+
92+
## Advanced
93+
94+
<details>
95+
<summary>Go beyond preselected tests</summary>
96+
97+
Visit the QA testing dashboard — [Moodle 5.3 QA testing](https://moodle.atlassian.net/jira/dashboards/10612) — to explore the full list of tests. For example, if you want tests for the "Book" activity aimed at "Teachers", you can [filter by those components](https://moodle.atlassian.net/issues/).
98+
99+
</details>
100+
101+
<details>
102+
<summary>Using your own site</summary>
103+
104+
If your only available site is running a different Moodle version (for example, your organisation's live site), please don't use it for this QA cycle. We're testing 5.3 specifically, not a previous version.
105+
106+
If you do have your own site running the latest Moodle 5.3dev, check the [QA testing documentation for developers](/general/development/process/testing/qa) first, then go ahead and use it.
107+
108+
</details>
109+
110+
---

docs/qatesting/gettingstarted.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Getting Started
3+
tags:
4+
- Quality Assurance
5+
- Testing
6+
- Core development
7+
sidebar_position: 1
8+
---
9+
10+
{/* <!-- markdownlint-disable no-inline-html --> */}
11+
12+
A friendly guide for anyone thinking about joining a Moodle QA testing cycle for the first time.
13+
14+
:::note[Next QA Cycle]
15+
The [Moodle 5.3 QA cycle](https://moodle.atlassian.net/jira/dashboards/10612) opens 1st September 2026.
16+
:::
17+
18+
## How to start
19+
20+
**1. Set up your accounts** create an account on the [Moodle Tracker](https://moodle.atlassian.net/) (that's where you will report your test results) and an account on [moodle.org](https://moodle.org/login/index.php). Use the same email address for both accounts. See below for details. You can do this anytime.
21+
22+
<details>
23+
<summary>Details on setting up your accounts</summary>
24+
25+
**Setting up your account on the Moodle Tracker**
26+
27+
The Moodle Tracker is open to the public to view tickets. However, in order to assign tests to yourself and add comments you'll need to create an account on the Moodle Tracker. The Moodle Tracker is Moodle's issue-tracking system; it's how the whole community reports bugs and test results, not just testers. Sign-up takes a couple of minutes.
28+
29+
1. Visit the [Moodle Tracker login page](https://id.atlassian.com/login).
30+
2. From there you can log in using your Google, Microsoft, Apple, or Slack accounts.
31+
3. If you prefer, you can manually create a new account by entering your email address and clicking "Sign up".
32+
4. Enter the 6-digit code emailed to you to proceed with the account creation.
33+
5. Enter your name and click "Create account".
34+
35+
**Setting up your account on moodle.org**
36+
37+
If you don't already have a moodle.org account, create one using the same email address as your Tracker account; this is how we credit you and generate your tester badge.
38+
39+
1. Visit [moodle.org](https://moodle.org/login/index.php) and click "Create new account".
40+
2. Enter your age and country and click "Proceed".
41+
3. Read the site's policies and cookie policy, click the checkboxes to agree and then click "Next".
42+
4. Fill in the form and click "Create my account".
43+
44+
</details>
45+
46+
**2. Once the QA cycle is open, choose a test to run.** Start with an easy test that is unassigned or explore the full test case list. Both are the top two widgets on the [QA testing dashboard](https://moodle.atlassian.net/jira/dashboards/10612). Once you find a test you like, assign it to yourself on the Moodle Tracker.
47+
48+
<details>
49+
<summary>Details on picking your first test</summary>
50+
51+
Once the testing cycle is open, check for unassigned beginner test cases. This is the top widget on the [dashboard](https://moodle.atlassian.net/jira/dashboards/10612). Test cases are written as a series of steps with an expected result.
52+
53+
You will see three columns:
54+
55+
- **Key**: indicates the ID of the test
56+
- **Summary**: it's the title of the test
57+
- **Components**: the part of Moodle the test belongs to (e.g. 'Book activity', 'Quiz'). Particularly useful if you want to focus on an area you're already familiar with.
58+
59+
Here's how to find and assign yourself a test:
60+
61+
1. Browse tests for beginners in the first widget on the [dashboard](https://moodle.atlassian.net/jira/dashboards/10612)
62+
2. Once you find a test you are interested in, click on the MDLQA-XX under the 'Key' column.
63+
3. This opens the test on the Moodle Tracker.
64+
4. Read the whole thing once before assigning it to yourself, so you know what you're aiming for. You can see how many steps there are in the Description, so you can gauge how long it'll take.
65+
5. If you aren't interested, close it and keep browsing tests for beginners.
66+
6. If you're interested, assign it to yourself.
67+
68+
We'd suggest only assigning yourself tests you already have some familiarity with, or are genuinely curious to learn by doing. And you can unassign yourself from a test at any time; no explanation needed.
69+
70+
</details>
71+
72+
[Full list of tests for beginners](https://moodle.atlassian.net/issues/?filter=29296)
73+
74+
**3. Run the test.** Avoid setting up your own Moodle site and use the [Moodle QA testing site](https://qa.moodledemo.net/) — the login details are available on the test site landing page.
75+
76+
<details>
77+
<summary>Details on running a test on the shared site</summary>
78+
79+
Moodle QA testing site: [Moodle QA Testing Site](https://qa.moodledemo.net/)
80+
81+
⚠️ Before you start, remember a few points:
82+
83+
- The site resets hourly at the top of the hour (so at 01:00, 02:00, and so on) so please be mindful if you are running a long test.
84+
- Don't enter any personal or sensitive information into the site.
85+
- More information on the Moodle QA Testing Site can be found in the [QA Process page](/general/development/process/testing/qa#moodle-qa-testing-site)
86+
- When you start executing a test case, select the `Start testing` action to mark the test as `In Progress`.
87+
- If you have some questions, check out the [FAQ](./faq.md) for further assistance.
88+
89+
</details>
90+
91+
**4. Report the test result** on the Moodle Tracker: mark it Pass or Fail, add a short comment about the results, and attach the screenshots.
92+
93+
<details>
94+
<summary>Details on reporting your result</summary>
95+
96+
On the Moodle Tracker, mark the test Pass or Fail. Add a comment using the templates below; you can copy and paste them or use a browser extension.
97+
98+
Reminder: attach a screenshot and a short note if anything didn't work as expected. Your Pass/Fail marks are reviewed directly by the QA lead and used to sign off the release, so nothing you submit disappears into a void.
99+
100+
If something that's not related to the test fails, add the `qa_help_needed` label and leave a comment with your question; we'll get back to you. And if the test instructions themselves seem outdated or unclear, add the `qa_instructions_update` label and note which steps need fixing; that feedback helps the next tester too.
101+
102+
<details>
103+
<summary>Template for a failed test</summary>
104+
105+
:::tip[Environment]
106+
107+
- Site used: QA Testing Site / Local test site (Moodle version: 5.3dev Build: YYYYMMDD)
108+
- Browser: (name and version)
109+
- Device/OS: (e.g. Windows 11 / macOS / iOS / Android)
110+
- Role(s) used: Admin / Teacher / Student
111+
112+
:::
113+
:::danger[Test failed]
114+
It doesn't work according to instructions.
115+
116+
- Step that failed: Step #
117+
- Expected result: (What should have happened according to the instructions)
118+
- Actual result: (Describe precisely what happened, including any error messages or unexpected behavior)
119+
120+
:::
121+
:::warning[Questions/Doubts]
122+
If you are unsure whether this is a bug or just a confusing step, describe your doubts here.
123+
:::
124+
:::note
125+
Attached are screenshots or logs showing the failure:
126+
127+
- Step 1:
128+
- Step 2:
129+
- Step #:
130+
131+
At least one screenshot per critical step. Screenshots may be grouped if appropriate.
132+
:::
133+
</details>
134+
135+
<details>
136+
<summary>Template for a passed test</summary>
137+
138+
:::tip[Environment]
139+
140+
- Site used: QA Testing Site / Local test site (Moodle version: 5.3dev Build: YYYYMMDD)
141+
- Browser: (e.g. Firefox 148.0 / Chrome 145.0.7632.117 / Safari 26 / …)
142+
- Device/OS: (e.g. Windows 11 / macOS / Ubuntu / iOS / Android 14 / …)
143+
- Role(s) used: Admin / Teacher / Student
144+
145+
:::
146+
147+
Works according to instructions. Test passed!
148+
149+
:::note
150+
Attached are screenshots for:
151+
152+
- Step 1:
153+
- Step 2:
154+
- Step #:
155+
156+
At least one screenshot per critical step. Screenshots may be grouped if appropriate.
157+
158+
(Please ensure you have attached the files to this Jira issue)
159+
:::
160+
161+
By marking this test as PASS, I confirm that I followed the instructions exactly as written; all required preconditions were set up; no additional settings were modified; and the test description is up-to-date and clear.
162+
</details>
163+
164+
<details>
165+
<summary>How to install these templates on the Moodle Tracker (browser extension)</summary>
166+
167+
You can use these templates directly in Jira by installing the "Canned Responses Pro" for Jira browser extension. It's available for:
168+
169+
- [Chrome](https://chromewebstore.google.com/detail/canned-responses-pro-for/abiklfpogpkkcelofcplnokkehjgmchc)
170+
- [Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/canned-responses-pro-for-/aaihcmfhjhpblfehcjfgadlcaokkaomd)
171+
- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/canned-responses-for-jira/)
172+
173+
After installing the extension, a "Select template" dropdown will appear above the Jira comment editor. From there you can select the templates "MDLQA – Test Passed" and "MDLQA – Test Failed"
174+
![Canned Responses for QA](./_gettingstarted/qatemplates.png)
175+
</details>
176+
</details>
177+
178+
:::note
179+
This guide covers everything a new tester needs. If you'd like the complete picture, the [QA testing documentation](https://moodledev.io/general/development/process/testing/qa) has all the technical specifications.
180+
:::
181+
182+
Thanks for considering this. Every test result helps, even if it's just one or two. Welcome aboard, and see you in the cycle 😊
183+
184+
---

project-words.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ JMeter
4040
JWKS
4141
Kanban
4242
Laravel
43+
Lomman
4344
MAINNODE
4445
MDK
4546
MDL
@@ -310,6 +311,7 @@ tablespace
310311
tasklogs
311312
templatable
312313
temptables
314+
testingbadge
313315
texteditor
314316
themers
315317
thirdparty

sidebars/docs.js

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,20 @@ const sidebars = {
5454
type: 'doc',
5555
id: 'devupdate',
5656
},
57+
{
58+
label: 'QA Testing guides',
59+
type: 'category',
60+
items: [
61+
{
62+
type: 'autogenerated',
63+
dirName: 'qatesting',
64+
},
65+
],
66+
link: {
67+
type: 'doc',
68+
id: 'qatesting',
69+
},
70+
},
5771

5872
{
5973
type: 'html',

0 commit comments

Comments
 (0)