Skip to content
This repository was archived by the owner on May 18, 2024. It is now read-only.

Commit 887039f

Browse files
MGatnerMGatner
committed
Docs overhaul
1 parent 9c64351 commit 887039f

File tree

8 files changed

+193
-261
lines changed

8 files changed

+193
-261
lines changed

‎README.md‎

Lines changed: 56 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,76 @@
11
# ci4-module-tests
2-
Testing scaffold for PHPUnit tests in CodeIgniter 4
2+
3+
PHPUnit testing scaffold for CodeIgniter 4 modules
34

45
## Overview
56

6-
**CIModuleTests** is intended to be integrated into third-party modules for CodeIgniter 4.
7-
It provides a scaffold and basic examples of how to perform module testing dependent on the
8-
framework without being integrated into a specific project.
7+
Not a module itself but a testing scaffold for CodeIgniter 4 modules,
8+
**ci4-module-tests** makes it easy to setup PHPUnit tests in your modules.
99

10-
For more on Testing in CodeIgniter 4 visit the
11-
[User Guide](https://codeigniter4.github.io/CodeIgniter4/testing/).
10+
To read more on Unit Testing in CodeIgniter 4 visit the
11+
[User Guide](https://codeigniter4.github.io/userguide/testing/index.html).
1212

1313
## Installation
1414

15-
### New Projects
16-
17-
1. Clone this repo and merge the all files from **src/** into the root of your module.
18-
2. From your package root run `composer install` to install all the required support packages.
19-
3. Start your module code in **src/** and add your namespace to **composer.json**'s `autoload`
20-
4. Run `composer test` to initiate the tests.
21-
22-
### Existing Projects
23-
24-
Unless you are starting fresh you likely will already have your own versions of some of the
25-
package files in **src/**. In this case you will need to be sure to merge some necessary
26-
settings for **CIModuleTests**. In **composer.json**:
27-
* `repositories` needs an entry for `https://github.com/codeigniter4/CodeIgniter4`
28-
* `require-dev` needs the CodeIgniter 4 repo, PHPUnit, and Mockery
29-
* `autoload-dev` must supply the PSR4 namespace for the test supports
30-
See the provided [composer.json](src/composer.json) for examples.
31-
32-
Also review **src/.gitignore** for helpful additions so you don't track test results.
15+
Clone or download this repo and place **src/tests** and **src/phpunit.xml.dist** in your
16+
project root. Add the following lines to **composer.json**:
17+
```
18+
"repositories": [
19+
{
20+
"type": "vcs",
21+
"url": "https://github.com/codeigniter4/CodeIgniter4"
22+
}
23+
],
24+
"minimum-stability": "dev",
25+
"require-dev": {
26+
"phpunit/phpunit" : "^7.0",
27+
"mockery/mockery": "^1.0",
28+
"codeigniter4/codeigniter4": "dev-develop"
29+
},
30+
"autoload-dev": {
31+
"psr-4": {
32+
"CIModuleTests\\Support\\": "tests/_support"
33+
}
34+
},
35+
"scripts": {
36+
"test": "phpunit",
37+
"post-update-cmd": [
38+
"composer dump-autoload"
39+
]
40+
}
41+
```
3342

34-
### phpunit.xml
43+
If you are using version tracking you should exclude test results by adding this to
44+
**.gitignore**:
45+
```
46+
vendor/
47+
build/
48+
phpunit*.xml
49+
phpunit
50+
composer.lock
51+
```
3552

36-
**src/** includes a ready-to-use PHPUnit template in **phpunit.xml.dist**. You can keep this
37-
as is but if you plan to add environment info (like database connections) be sure to rename
38-
it to **phpunit.xml** and prevent it from being tracked via **.gitignore**.
53+
Examples of **composer.json** and **.gitignore** are located in the [examples/](examples/)
54+
folder if you need a starting point.
3955

40-
## Customizing
56+
## Updating
4157

42-
The **_support** directory comes loaded with easy-to-use examples of test cases and their
43-
support files, but you will probably want to modify or replace these with your own versions.
44-
There is no harm in leaving files in place you do not need.
45-
* **tests/_support/DatabaseTestCase.php**
46-
* **tests/_support/SessionTestCase.php**
47-
* **tests/_support/DatabaseTestCase.php**
48-
* **tests/_support/Database/Migrations/create_test_tables.php**
49-
* **tests/_support/Database/Seeds/ExampleSeeder.php**
50-
* **tests/_support/Models/ExampleModel.php**
58+
As this repo is updated with bugfixes and improvements you will want to update your
59+
modules that use it. Because files need to be copied in place manually you will have to
60+
handle updates manually by cloning or downloading this repo and merging changed files
61+
into your project. "Watch" this repo to be notified of new releases and changes.
5162

5263
## Creating Tests
5364

54-
All tests go in the **tests/** directory. There are two generic subfolders for you,
55-
**unit** and **database** but feel free to make your own. Tests must extend the appropriate
56-
test case:
57-
* For basic tests extend `CodeIgniter\Test\CIUnitTestCase`
58-
* For database tests extend `CIModuleTests\Support\DatabaseTestCase`
59-
* For session tests extend `CIModuleTests\Support\SessionTestCase`
60-
61-
Tests are individual methods within each file. Method names must start with the word "test":
62-
`testUserSync()` `testOutputColor()` `testFooBar()`
63-
64-
### Database Tests
65+
See the docs on [Creating Tests](docs/CREATING.md).
6566

66-
If you are using database tests that require a live database connect you will need to
67-
rename **phpunit.xml.dist** to **phpunit.xml**, uncomment the database configuration lines
68-
and add your connection details. Example directories and files are provided for test Seeds
69-
and Models, which you can modify or replace with your own. Also be sure to modify
70-
**tests/_support/DatabaseTestCase.php** to point to your seed and include any additional
71-
steps in `setUp()`.
67+
## Running Tests
7268

73-
### Session Tests
74-
75-
Similarly there is a pre-configured test case available with a mock session configured to
76-
make testing sessions easy: **tests/_support/SessionTestCase.php**.
69+
From your package root run `composer install` (or `composer upgrade`) to install all the
70+
required support packages, then run `composer test` to initiate the tests. Test results
71+
and code coverage will be written to standard output and formatted log versions will go
72+
in **build/logs/**.
7773

7874
## Code Coverage
7975

80-
**CIModuleTests** comes preconfigured to run code coverage as part of the testing. You will
81-
need to have a code coverage driver installed to use this feature, such as
82-
[Xdebug](https://xdebug.org). **CIModuleTests** assumes your source code is in **src/**;
83-
if your code is somewhere else then modify the following line in **phpunit.xml.dist** :
84-
```
85-
<directory suffix=".php">./src</directory>
86-
```
87-
Other common modifications would be removing the attributes from the whitelist element:
88-
```
89-
<whitelist addUncoveredFilesFromWhitelist="true" processUncoveredFilesFromWhitelist="true">
90-
```
91-
... and adjusting the output location and format of the coverage reports:
92-
```
93-
<logging>
94-
<log type="coverage-clover" target="build/logs/clover.xml"/>
95-
<log type="coverage-html" target="build/logs/html"/>
96-
<log type="coverage-text" target="php://stdout" showUncoveredFiles="true"/>
97-
</logging>
98-
```
99-
100-
## Updating
101-
102-
As this repo is updated with bugfixes and improvements you will want to update the code
103-
merged into your modules. Because tests need to be top-level and should not include their
104-
own repository info you will need to handle updates manually.
105-
106-
If you added **CIModuleTests** to your package via Composer you can access the latest
107-
version by running `composer update` and merging files from
108-
**vendor/mgatner/ci-module-tests/src/** into your **tests/** directory.
76+
See the docs on [Code Coverage](docs/COVERAGE.md).

‎composer.json‎

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎docs/COVERAGE.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Code Coverage
2+
3+
>> Code coverage is a term used in software testing to describe how much program source
4+
>> code is covered by a testing plan. -[TechnoPedia](https://www.techopedia.com/definition/22535/code-coverage)
5+
6+
## Overview
7+
8+
**ci4-module-tests** comes preconfigured to handle code coverage in addition to the unit tests.
9+
You will need to have a code coverage driver installed to use this feature, such as
10+
[Xdebug](https://xdebug.org).
11+
12+
## Setup
13+
14+
**ci4-module-tests** assumes your source code is in **src/**; if your code is somewhere else
15+
then you will need to modify the following line in your PHPUnit XML file:
16+
```
17+
<directory suffix=".php">./src</directory>
18+
```
19+
20+
## PHPUnit.xml
21+
22+
**ci4-module-tests** includes a ready-to-use PHPUnit template in **phpunit.xml.dist**.
23+
Common practice is to create a local copy of this file as **phpunit.xml** and add any
24+
sensitive or environment info (like database connections). Prevent **phpunit.xml** from
25+
being tracked in your repo by adding it to **.gitignore**.
26+
27+
>> PHPUnit will always use **phpunit.xml** before **phpunit.xml.dist**, if it is found.
28+
29+
### Exclusions
30+
31+
In addition to the code source mentioned above, PHPUnit can be configured to exclude files
32+
that are not relevant to testing or would otherwise cause the coverage calculations to fail.
33+
**ci4-module-tests** provides a few files common to CodeIgniter 4 but you may need to add
34+
your own:
35+
```
36+
<exclude>
37+
<directory suffix=".php">./src/Views</directory>
38+
<file>./src/Config/Routes.php</file>
39+
</exclude>
40+
```
41+
42+
### Logging
43+
44+
Another common change is adjusting the output location and format of the coverage reports:
45+
```
46+
<logging>
47+
<log type="coverage-html" target="build/logs/html"/>
48+
<log type="coverage-clover" target="build/logs/clover.xml"/>
49+
<log type="coverage-php" target="build/logs/coverage.serialized"/>
50+
<log type="coverage-text" target="php://stdout" showUncoveredFiles="false"/>
51+
<log type="testdox-html" target="build/logs/testdox.html"/>
52+
<log type="testdox-text" target="build/logs/testdox.txt"/>
53+
<log type="junit" target="build/logs/logfile.xml"/>
54+
</logging>
55+
```
56+
57+
To read more on logging and options see the
58+
[Loggin Section](https://phpunit.readthedocs.io/en/8.3/logging.html) of the PHPUnit Guide.
59+
60+
For more information on using the PHPUnit XML file generally see the
61+
[Configuration Section](https://phpunit.readthedocs.io/en/8.3/configuration.html) of the guide.

‎docs/CREATING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Creating Tests
2+
3+
## Resources
4+
* [CodeIgniter 4 User Guide on Testing](https://codeigniter4.github.io/userguide/testing/index.html)
5+
* [PHPUnit docs](https://phpunit.readthedocs.io/en/8.3/index.html)
6+
* [Mockery docs](http://docs.mockery.io/en/latest/)
7+
8+
## Test Cases
9+
10+
Every test needs a *test case*, or class that your tests extend. CodeIgniter 4
11+
provides a few you may use directly:
12+
* `CodeIgniter\Test\CIUnitTestCase` - for basic tests with no other service needs
13+
* `CodeIgniter\Test\CIDatabaseTestCase` - for tests that need database access
14+
15+
**ci-module-tests** also provides some examples:
16+
* `CIModuleTests\Support\DatabaseTestCase` - for database tests, pre-configured for migrations, seeds, and models from **tests/_support**
17+
* `CIModuleTests\Support\SessionTestCase` - for session tests, pre-configured with a mock session driver
18+
19+
Most of the time you will want to write your own test cases to hold functions and services
20+
common to your test suites.
21+
22+
## Tests
23+
24+
All tests go in the **tests/** directory. **ci-module-tests** provides two generic
25+
subfolders for you **unit** and **database** but feel free to make your own. Each test file
26+
is a class that extends a **Test Case** (see above) and contains methods for each individual
27+
test. These method names must start with the word "test" and should have descriptive names
28+
for precisely what they are testing: `testUserCanModifyFile()` `testOutputColorMatchesInput()`
29+
`testIsLoggedInFailsWithInvalidUser()`
30+
31+
### Database Tests
32+
33+
**ci-module-tests** provides a examples for migrating, seeding, and testing against a mock
34+
or live<sup>1</sup> database. The example files can be modified or replaced with your own:
35+
* **tests/_support/Database/Migrations/create_test_tables.php**
36+
* **tests/_support/Database/Seeds/ExampleSeeder.php**
37+
* **tests/_support/Models/ExampleModel.php**
38+
39+
Be sure to modify the test case (or create your own) to point to your seed and migrations
40+
and include any additional steps in `setUp()`:
41+
* **tests/_support/DatabaseTestCase.php**
42+
43+
<sup>1</sup> Note: If you are using database tests that require a live database connection you will need
44+
to rename **phpunit.xml.dist** to **phpunit.xml**, uncomment the database configuration
45+
lines and add your connection details. Prevent **phpunit.xml** from being tracked in your
46+
repo by adding it to **.gitignore**.
47+
48+
### Session Tests
49+
50+
Similar to the database test case, **ci-module-tests** provides a test case pre-configured
51+
with the mock session class to make testing sessions easy:
52+
* **tests/_support/SessionTestCase.php**

‎examples/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
vendor/
2+
build/
3+
phpunit*.xml
4+
phpunit
5+
composer.lock
6+
.DS_Store

‎src/composer.json‎ renamed to ‎examples/composer.json‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
11
{
2-
"name": "mgatner/ci-module-tests",
3-
"description": "Testing scaffold for PHPUnit tests in CodeIgniter 4",
2+
"name": "vendor/mymodule",
3+
"description": "My module for CodeIgniter 4 (with tests!)",
44
"keywords": [
55
"codeigniter",
66
"codeigniter4",
7-
"phpunit",
8-
"tests",
9-
"modules",
10-
"coverage"
7+
"modules"
118
],
12-
"homepage": "https://github.com/mgatner/ci-module-tests",
9+
"homepage": "https://example.com",
1310
"license": "MIT",
1411
"authors": [
1512
{
16-
"name": "Matthew Gatner",
17-
"email": "mgatner@tattersoftware.com",
18-
"homepage": "https://tattersoftware.com",
13+
"name": "Jill Developer",
14+
"email": "jill@example.com",
15+
"homepage": "https://ecample.com",
1916
"role": "Developer"
2017
}
2118
],
@@ -35,6 +32,11 @@
3532
"mgatner/ci-module-tests": "^1.0",
3633
"codeigniter4/codeigniter4": "dev-develop"
3734
},
35+
"autoload": {
36+
"psr-4": {
37+
"Vendor\\MyModule\\": "src"
38+
}
39+
},
3840
"autoload-dev": {
3941
"psr-4": {
4042
"CIModuleTests\\Support\\": "tests/_support"

0 commit comments

Comments
 (0)