Skip to content

Commit c7834b3

Browse files
bembelimenbembelimen
authored
Merge pull request #12 from rdeutz/testing-docs
Add testing documentation
2 parents 4c8c58d + f9a2715 commit c7834b3

File tree

11 files changed

+245
-0
lines changed

11 files changed

+245
-0
lines changed

‎docs/testing/automated/concepts.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
Concepts
6+
=============
7+
8+
For Joomla! we are using different strategies to test the application.
9+
10+
# System Testing versus Unit Testing
11+
12+
System Testing and Unit Testing are complementary test strategies. In Joomla!, Unit Testing is mainly used to test the framework classes (for example, the classes in libraries/joomla). Unit tests test that an individual method (also known as function) in a class does what it is supposed to do. For example, a unit test is used to test that the methods in the JString class work as expected. Unit testing provides confidence that the framework classes work as expected and allows you to refactor these classes (improve the code without changing the functionality) and still have confidence that they still work correctly.
13+
14+
System tests test that the application works correctly from the user point of view. For example, a system test can test something simple, for example, that you can create a new menu item for a single article and show the menu item on the site. Or a system test can test something more detailed, for example that the parameters for a module all work as expected.
15+
16+
Designing and creating system tests requires that you know how to use the application. It does not require that you understand how the program is written. Application knowledge is more important than programming knowledge, so system tests can be designed and written by people with less technical knowledge of PHP or the Joomla! framework.

‎docs/testing/automated/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
Automated Testing
6+
=============
7+
8+
Here you will find information about our automated testing, how to write tests and how to set it up.

‎docs/testing/automated/system/assets/cypress-window1.jpg‎

192 KB
Loading

‎docs/testing/automated/system/assets/cypress-window2.jpg‎

470 KB
Loading

‎docs/testing/automated/system/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
6+
System Testing
7+
===============
8+
9+
We are using [Cypress](https://docs.cypress.io/guides/overview/why-cypress) for our system (end2end) testing.

‎docs/testing/automated/system/setup.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
6+
Setup your testing environment
7+
===============
8+
9+
## Prepare your Workstation
10+
11+
You need a set of tools to have a good testing setup. Tools you should have:
12+
13+
* git
14+
* node (16.16.0 is the current LTS)
15+
* database (mysql 5.6+, mariaDB 10.1+, postgres 11.0+)
16+
* PHP (good to have different versions and the ability to switch)
17+
* Composer, [Installation instructions here](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos)
18+
* Webserver (apache 2.4+, nginx 1.18+)
19+
* Editor (PhpStorm, Visual Studio Code)
20+
21+
:::note
22+
23+
This is the same toolset you need for unit testing
24+
25+
:::
26+
27+
## MAC OS
28+
29+
As always there are different ways of installing the listed software. One way is the use of [Valet](https://laravel.com/docs/9.x/valet) in combination with [Homebrew](https://brew.sh/)
30+
31+
Now as you have all tools installed you can clone the [joomla-cms repository](https://github.com/joomla/joomla-cms).
32+
33+
1. Open a terminal
34+
2. Go into a directory on you workstation.
35+
3. clone the joomla-cms repository: ```git clone https://github.com/joomla/joomla-cms.git``` another option here is to fork the joomla-cms repo and then clone your fork. We recommend the 2nd way because then you can make changes and Pull Request directly.
36+
4. Go into the joomla-cms directory
37+
5. If you have installed valet, run ```valet link```
38+
5. Run ```composer install```
39+
6. Run ```npm ci```
40+
7. Create a ```cypress.env.json``` file. This file allows to overwrite config setting from ```cypress.config.js```
41+
42+
Here is a example ```cypress.env.json```
43+
44+
```json
45+
{
46+
"sitename": "Joomla CMS Test Local",
47+
"name": "jane doe",
48+
"email": "[email protected]",
49+
"username": "local-admin",
50+
"password": "joomla-17082005",
51+
"db_type": "MySQLi",
52+
"db_host": "localhost",
53+
"db_name": "test_joomla",
54+
"db_user": "root",
55+
"db_password": "password",
56+
"db_prefix": "jos_"
57+
}
58+
```
59+
You don't need all settings, just look what you have to change for your local environment compared to ```cypress.config.js```
60+
61+
8. Run ```cypress open --e2e --browser=chrome --config baseUrl=http://joomla-cms.test```
62+
63+
This will open two windows, one you can ignore and one to run the tests
64+
65+
66+
![Cypress Window 1](./assets/cypress-window1.jpg)
67+
68+
In the following window you can select test and let them run. You need to install first.
69+
70+
![Cypress Window 2](./assets/cypress-window2.jpg)
71+
72+
73+
## Windows
74+
75+
76+
77+
78+
:::caution TODO
79+
80+
This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
81+
82+
:::

‎docs/testing/automated/system/writing-test.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
6+
Writing Tests
7+
===============
8+
9+
10+

‎docs/testing/automated/unit/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
6+
Unit Testing
7+
===============
8+
9+
:::caution TODO
10+
11+
This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
12+
13+
:::

‎docs/testing/automated/unit/setup.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
6+
Setup your testing environment
7+
===============
8+
9+
## Prepare your Workstation
10+
11+
You need a set of tools to have a good testing setup. Tools you should have:
12+
13+
* git
14+
* node (16.16.0 is the current LTS)
15+
* database (mysql 5.6+, mariaDB 10.1+, postgres 11.0+)
16+
* PHP (good to have different versions and the ability to switch)
17+
* Composer, [Installation instructions here](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos)
18+
* Webserver (apache 2.4+, nginx 1.18+) - **optional**
19+
* Editor (PhpStorm, Visual Studio Code)
20+
21+
:::note
22+
23+
This is pretty much the same toolset you need for system testing
24+
25+
:::
26+
27+
## MAC OS
28+
29+
As always there are different ways of installing the listed software. One way is the use of [Valet](https://laravel.com/docs/9.x/valet) in combination with [Homebrew](https://brew.sh/)
30+
31+
Now as you have all tools installed you can clone the [joomla-cms repository](https://github.com/joomla/joomla-cms).
32+
33+
1. Open a terminal
34+
2. Go into a directory on you workstation.
35+
3. clone the joomla-cms repository: ```git clone https://github.com/joomla/joomla-cms.git``` another option here is to fork the joomla-cms repo and then clone your fork. We recommend the 2nd way because then you can make changes and Pull Request directly.
36+
4. Go into the joomla-cms directory
37+
5. **Optional** - If you have installed valet, run ```valet link```
38+
5. Run ```composer install```
39+
6. Run ```npm ci```
40+
7. Copy ```phpunit.xml.dist``` file to ```phpunit.xml```. This file allows config setting for phpunit.
41+
42+
Here is a example ```phpunit.xml```
43+
44+
```xml
45+
<?xml version="1.0" encoding="UTF-8"?>
46+
<phpunit bootstrap="tests/Unit/bootstrap.php" colors="false">
47+
<testsuites>
48+
<testsuite name="Unit">
49+
<directory suffix="Test.php">./tests/Unit/Libraries</directory>
50+
</testsuite>
51+
<testsuite name="Integration">
52+
<directory suffix="Test.php">./tests/Integration/Libraries</directory>
53+
</testsuite>
54+
</testsuites>
55+
<php>
56+
<const name="JTEST_DB_ENGINE" value="mysqli" />
57+
<const name="JTEST_DB_HOST" value="mysql" />
58+
<const name="JTEST_DB_NAME" value="test_joomla" />
59+
<const name="JTEST_DB_USER" value="root" />
60+
<const name="JTEST_DB_PASSWORD" value="password" />
61+
</php>
62+
</phpunit>
63+
```
64+
65+
8. Run ```phpunit --testdox```
66+
67+
68+
69+
## Windows
70+
71+
72+
73+
74+
:::caution TODO
75+
76+
This page is unfinished, please use the **Edit this Page** link at the bottom of this page to help make it more useful.
77+
78+
:::

‎docs/testing/index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
Testing
6+
=============
7+
8+
# Overview
9+
10+
Testing Software is an important part of software development. For Joomla! we have different levels of testing:
11+
12+
## Automated Testing
13+
14+
For the automated testing we are using a continus integration (CI) server drone. Any change that is made runs a series of tests on the CI system. We test if the code style for PHP, CSS and javascript is correct, run unit test for the supported PHP versions and run end to end tests. All this not only runs on different PHP version we are also testing different database version. At the end of the test we create an installable package with the changes included to support our manually testing. If something fails we save information about the reason.
15+
16+
## Manually Testing
17+
While automated testing is more focused on making sure that a change doesn't break existing functionality, is manually testing focused on the change itself. Always tow people have to confirm that a change does for what is made. This can be a bugfix or new functionality.

0 commit comments

Comments
 (0)