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

Commit 091a67a

Browse files
MGatnerMGatner
committed
Start content from ModuleTests
1 parent 0eebd12 commit 091a67a

File tree

15 files changed

+565
-2
lines changed

15 files changed

+565
-2
lines changed

‎README.md‎

Lines changed: 76 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,76 @@
1-
# project-tests
2-
PHPUnit testing scaffold for CodeIgniter 4 projects
1+
# ModuleTests
2+
3+
PHPUnit testing scaffold for CodeIgniter 4 modules
4+
5+
## Overview
6+
7+
Not a module itself but a testing scaffold for CodeIgniter 4 modules,
8+
**module-tests** makes it easy to setup PHPUnit tests in your modules.
9+
10+
To read more on Unit Testing in CodeIgniter 4 visit the
11+
[User Guide](https://codeigniter4.github.io/userguide/testing/index.html).
12+
13+
## Installation
14+
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+
"ModuleTests\\Support\\": "tests/_support"
33+
}
34+
},
35+
"scripts": {
36+
"test": "phpunit",
37+
"post-update-cmd": [
38+
"composer dump-autoload"
39+
]
40+
}
41+
```
42+
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+
```
52+
53+
Examples of **composer.json** and **.gitignore** are located in the [examples/](examples/)
54+
folder if you need a starting point.
55+
56+
## Updating
57+
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.
62+
63+
## Creating Tests
64+
65+
See the docs on [Creating Tests](docs/CREATING.md).
66+
67+
## Running Tests
68+
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/**.
73+
74+
## Code Coverage
75+
76+
See the docs on [Code Coverage](docs/COVERAGE.md).

‎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** starts with 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+
Output is available in a variety of formats (see the [Logging Section](https://phpunit.readthedocs.io/en/8.3/logging.html)
45+
of the PHPUnit Guide). You can adjust the default location and format of the reports by
46+
modifying the `<logging>` tag:
47+
```
48+
<logging>
49+
<log type="coverage-html" target="build/logs/html"/>
50+
<log type="coverage-clover" target="build/logs/clover.xml"/>
51+
<log type="coverage-php" target="build/logs/coverage.serialized"/>
52+
<log type="coverage-text" target="php://stdout" showUncoveredFiles="false"/>
53+
<log type="testdox-html" target="build/logs/testdox.html"/>
54+
<log type="testdox-text" target="build/logs/testdox.txt"/>
55+
<log type="junit" target="build/logs/logfile.xml"/>
56+
</logging>
57+
```
58+
59+
For more information on using the PHPUnit XML file generally see the
60+
[Configuration Section](https://phpunit.readthedocs.io/en/8.3/configuration.html)
61+
of the guide.

‎docs/CREATING.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
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 that 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+
**ModuleTests** also provides some examples:
16+
* `ModuleTests\Support\DatabaseTestCase` - for database tests, pre-configured for migrations, seeds, and models from **tests/_support**
17+
* `ModuleTests\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. **ModuleTests** 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 the individual
27+
tests. 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+
Writing tests is an art, and there are many resources available to help learn how. Review
32+
the links above and always pay attention to your [Code Coverage](docs/COVERAGE.md).
33+
34+
### Database Tests
35+
36+
**ModuleTests** provides examples for migrating, seeding, and testing against a mock
37+
or live<sup>1</sup> database. The example files can be modified or replaced with your own:
38+
* **tests/_support/Database/Migrations/create_test_tables.php**
39+
* **tests/_support/Database/Seeds/ExampleSeeder.php**
40+
* **tests/_support/Models/ExampleModel.php**
41+
42+
Be sure to modify the test case (or create your own) to point to your seed and migrations
43+
and include any additional steps to be run before tests in the `setUp()` method:
44+
* **tests/_support/DatabaseTestCase.php**
45+
46+
<sup>1</sup> Note: If you are using database tests that require a live database connection you will need
47+
to rename **phpunit.xml.dist** to **phpunit.xml**, uncomment the database configuration
48+
lines and add your connection details. Prevent **phpunit.xml** from being tracked in your
49+
repo by adding it to **.gitignore**.
50+
51+
### Session Tests
52+
53+
Similar to database testing, **ModuleTests** provides a test case pre-configured
54+
with the [mock session class](https://codeigniter4.github.io/userguide/testing/overview.html#mocking-services)
55+
to make testing sessions easier:
56+
* **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

‎examples/composer.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"name": "vendor/mymodule",
3+
"description": "My module for CodeIgniter 4 (with tests!)",
4+
"keywords": [
5+
"codeigniter",
6+
"codeigniter4",
7+
"modules"
8+
],
9+
"homepage": "https://example.com",
10+
"license": "MIT",
11+
"authors": [
12+
{
13+
"name": "Jill Developer",
14+
"email": "jill@example.com",
15+
"homepage": "https://ecample.com",
16+
"role": "Developer"
17+
}
18+
],
19+
"repositories": [
20+
{
21+
"type": "vcs",
22+
"url": "https://github.com/codeigniter4/CodeIgniter4"
23+
}
24+
],
25+
"minimum-stability": "dev",
26+
"require": {
27+
"php" : ">=7.2"
28+
},
29+
"require-dev": {
30+
"phpunit/phpunit" : "^7.0",
31+
"mockery/mockery": "^1.0",
32+
"codeigniter4/codeigniter4": "dev-develop"
33+
},
34+
"autoload": {
35+
"psr-4": {
36+
"Vendor\\MyModule\\": "src"
37+
}
38+
},
39+
"autoload-dev": {
40+
"psr-4": {
41+
"ModuleTests\\Support\\": "tests/_support"
42+
}
43+
},
44+
"scripts": {
45+
"test": "phpunit",
46+
"post-update-cmd": [
47+
"composer dump-autoload"
48+
]
49+
}
50+
}

‎src/phpunit.xml.dist‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<phpunit bootstrap="tests/_support/bootstrap.php"
3+
backupGlobals="false"
4+
colors="true"
5+
convertErrorsToExceptions="true"
6+
convertNoticesToExceptions="true"
7+
convertWarningsToExceptions="true"
8+
stopOnError="false"
9+
stopOnFailure="false"
10+
stopOnIncomplete="false"
11+
stopOnSkipped="false">
12+
<testsuites>
13+
<testsuite name="all">
14+
<directory>./tests</directory>
15+
</testsuite>
16+
</testsuites>
17+
18+
<filter>
19+
<whitelist addUncoveredFilesFromWhitelist="true" processUncoveredFilesFromWhitelist="true">
20+
<directory suffix=".php">./src</directory>
21+
<exclude>
22+
<directory suffix=".php">./src/Views</directory>
23+
<file>./src/Config/Routes.php</file>
24+
</exclude>
25+
</whitelist>
26+
</filter>
27+
28+
<logging>
29+
<log type="coverage-html" target="build/logs/html"/>
30+
<log type="coverage-clover" target="build/logs/clover.xml"/>
31+
<log type="coverage-php" target="build/logs/coverage.serialized"/>
32+
<log type="coverage-text" target="php://stdout" showUncoveredFiles="false"/>
33+
<log type="testdox-html" target="build/logs/testdox.html"/>
34+
<log type="testdox-text" target="build/logs/testdox.txt"/>
35+
<log type="junit" target="build/logs/logfile.xml"/>
36+
</logging>
37+
38+
<php>
39+
<env name="app.baseURL" value="http://example.com"/>
40+
<env name="CI_ENVIRONMENT" value="testing"/>
41+
<!-- <env name="database.tests.hostname" value="localhost"/> -->
42+
<!-- <env name="database.tests.database" value="tests"/> -->
43+
<!-- <env name="database.tests.username" value="tests_user"/> -->
44+
<!-- <env name="database.tests.password" value=""/> -->
45+
<!-- <env name="database.tests.DBDriver" value="MySQLi"/> -->
46+
<!-- <env name="database.tests.DBPrefix" value="tests_"/> -->
47+
<env name="database.tests.database" value=":memory:"/>
48+
<env name="database.tests.DBDriver" value="SQLite3"/>
49+
</php>
50+
</phpunit>

‎src/tests/_support/Database/Migrations/2019-09-02-092335_create_test_tables.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<?php namespace ModuleTests\Support\Database\Migrations;
2+
3+
use CodeIgniter\Database\Migration;
4+
5+
class CreateTestTables extends Migration
6+
{
7+
public function up()
8+
{
9+
$fields = [
10+
'name' => ['type' => 'varchar', 'constraint' => 31],
11+
'uid' => ['type' => 'varchar', 'constraint' => 31],
12+
'class' => ['type' => 'varchar', 'constraint' => 63],
13+
'icon' => ['type' => 'varchar', 'constraint' => 31],
14+
'summary' => ['type' => 'varchar', 'constraint' => 255],
15+
'created_at' => ['type' => 'datetime', 'null' => true],
16+
'updated_at' => ['type' => 'datetime', 'null' => true],
17+
'deleted_at' => ['type' => 'datetime', 'null' => true],
18+
];
19+
20+
$this->forge->addField('id');
21+
$this->forge->addField($fields);
22+
23+
$this->forge->addKey('name');
24+
$this->forge->addKey('uid');
25+
$this->forge->addKey(['deleted_at', 'id']);
26+
$this->forge->addKey('created_at');
27+
28+
$this->forge->createTable('factories');
29+
}
30+
31+
public function down()
32+
{
33+
$this->forge->dropTable('factories');
34+
}
35+
}

‎src/tests/_support/Database/Seeds/ExampleSeeder.php‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<?php namespace ModuleTests\Support\Database\Seeds;
2+
3+
class ExampleSeeder extends \CodeIgniter\Database\Seeder
4+
{
5+
public function run()
6+
{
7+
$factories = [
8+
[
9+
'name' => 'Test Factory',
10+
'uid' => 'test001',
11+
'class' => 'Factories\Tests\NewFactory',
12+
'icon' => 'fas fa-puzzle-piece',
13+
'summary' => 'Longer sample text for testing',
14+
],
15+
[
16+
'name' => 'Widget Factory',
17+
'uid' => 'widget',
18+
'class' => 'Factories\Tests\WidgetPlant',
19+
'icon' => 'fas fa-puzzle-piece',
20+
'summary' => 'Create widgets in your factory',
21+
],
22+
[
23+
'name' => 'Evil Factory',
24+
'uid' => 'evil-maker',
25+
'class' => 'Factories\Evil\MyFactory',
26+
'icon' => 'fas fa-book-dead',
27+
'summary' => 'Abandon all hope, ye who enter here',
28+
]
29+
];
30+
31+
$builder = $this->db->table('factories');
32+
33+
foreach ($factories as $factory)
34+
{
35+
$builder->insert($factory);
36+
}
37+
}
38+
}

0 commit comments

Comments
 (0)