From 076e654d68761625fde2b47d1da57d2e6cee9eb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alejandro=20L=C3=B3pez=20Ariza?=
<45979455+alopezari@users.noreply.github.com>
Date: Fri, 20 Jan 2023 15:14:41 +0100
Subject: [PATCH] Created Writing high-quality testing instructions (markdown)
---
Writing-high-quality-testing-instructions.md | 80 ++++++++++++++++++++
1 file changed, 80 insertions(+)
create mode 100644 Writing-high-quality-testing-instructions.md
diff --git a/Writing-high-quality-testing-instructions.md b/Writing-high-quality-testing-instructions.md
new file mode 100644
index 0000000..66c7b42
--- /dev/null
+++ b/Writing-high-quality-testing-instructions.md
@@ -0,0 +1,80 @@
+## What is a test?
+
+A test is a method that we can use to check that something meets certain criteria. It is typically defined as a procedure which contains the steps required to put the system under test in a certain state before executing the action to be checked. Therefore, a test consists of the following stages:
+- **Preconditions:** All the steps that need to be performed to put the system in the desired state before executing the action we want to check. A test could have many preconditions.
+- **Action:** This is the exact step that causes the change we want to check in the system. It should be only one because each test should ideally cover one thing at a time.
+- **Validation:** Relates to the steps to be performed in order to validate the result of performing the action in the system. A test could validate more than one thing.
+
+For example, in the process of adding an item to the cart:
+- The **preconditions** would be all the steps involved in:
+ - The product creation process.
+ - Logging as a shopper.
+ - Heading to the shop page where the products are listed.
+- The **action** would be clicking the *“Add to cart”* button in the desired product.
+- The **validation** stage would include checking that the cart icon (if any) shows 1 more item and the product we selected is now included in the cart.
+
+Specifying what are the preconditions, action and validation can be quite beneficial when understanding the scope of a test, because:
+- The **preconditions** describe what we have to do so that we can execute the test successfully.
+- The **action** lets us know the purpose of the test, in other words, it is the key to understanding what we need to test.
+- The **validation** stage lets us know what to expect when executing the test.
+
+In this context, we will refer to testing instructions as the tests we need to execute in order to validate that the changes delivered in a Pull Request or Release work as expected.
+
+## Flow to write good testing instructions
+1. **Outline the user flows** you want to cover.
+2. **Define the environment** where the testing instructions should be executed (server, PHP version, WP version, required plugins, etc), and start writing the testing instructions as if you were starting from a fresh install.
+3. Identify the **preconditions**, **action** and **validation** steps.
+4. Write **as many preconditions as you need** to explain how to set up the state of WooCommerce so that you can execute the desired action to test every flow.
+ 1. Try to be detailed when explaining the interactions the user needs to perform in WooCommerce.
+ 2. If there are several preconditions for a user flow that is explained in a public guide, feel free to simply link the guide in the testing instructions instead of writing several steps. For example, *"Enable dev mode in WooCommerce Payments by following the steps mentioned [here](https://woocommerce.com/document/woocommerce-payments/testing-and-troubleshooting/dev-mode/)"*.
+5. Write **the action step**, which should cover the specific action that we want to test as part of this user flow.
+6. Write **as many validation steps** as needed in order to assess that the actual result meets expectations.
+ 1. Bear in mind to check only the steps needed to validate that this change works.
+
+
+### Considerations for writing high-quality testing instructions
+- Define the testing instructions in a way that they can be **understood and followed by everybody**, even for people new to WooCommerce.
+- Make sure to describe every detail and **avoid assuming knowledge**, the spectrum of readers might be wide and some people would not know the concepts behind what is being assumed. For example, instead of saying *“Enable the [x] experiment”*, say something like:
+```
+- Install the WooCommerce Beta Tester plugin.
+- Go to `Tools > WCA Test Helper > Experiments`.
+- Toggle the [x] experiment.
+```
+- Always try to explain in detail **where the user should head to**, for example instead of saying “Go to the Orders page as admin”, say “Go to [url]” or even “Go to WooCommerce > Orders”.
+- Try to use real test data. For example, instead of saying *"Enter a name for the product"*, say something like *"Enter 'Blue T-Shirt' as the product name"*. This will make it more self-explanatory and remove potential doubts related to assuming knowledge.
+- Make sure you **keep your testing instructions updated** if they become obsolete as part of a new commit.
+- If the testing instructions require to add custom code, please **provide the code snippet**.
+- If the testing instructions require to install a plugin, please **provide a link to this plugin, or the zip file** to install it.
+- If the testing instructions require to hit an API endpoint, please provide the **link to the endpoint documentation**.
+- Ideally **provide screenshots and/or videos** that supported what the testing instructions are explaining.
+
+
+## Examples
+### Good quality testing instructions
+#### Example 1
+
+
+#### Example 2
+
+
+### Improving real testing instructions
+
+In this section, you will see some real examples of testing instructions that have room for improvement (before) and how we can tweak them (after).
+
+#### Before
+
+
+#### After
+
+
+#### Improvements
+
+
+#### Before
+
+
+#### After
+
+
+#### Improvements
+