documentation update

Author: Malte Riesch

README.md

@@ -3,47 +3,59 @@
 Test-DB-Acle
 ============
 
-Pronounced test debacle. I guess you can leave out the -db- part if you want a slightly shorter word and feel so inclined.
+Pronounced test debacle... I guess you can leave out the -db- part if you want a slightly shorter word and feel so inclined.
 
-What is Test-DB-Acle? A short mission statement.
+What is Test-DB-Acle? 
 ------------------------------------------------
 
 Test-DB-Acle is a PHP library to facilitate writing easy and concise tests for the database layer. 
 
-It is my belief that writing tests should be as easy as possible for the developer, and they should also be as easy to read as possible for other developers to pick up (Ah, so easy to give advice..!)
+It is my belief that writing tests should be as easy as possible for the developer, and they should also be as easy to read as possible for other developers to pick up.
 
 This means any test data in the test should be relevant to the test scenario only. Most database tables however have non-null columns that require you to enter dummy data that is just introducing cognitive noise  to the test. 
 
-Test-Db-Acle aims to take this burden away from the developer. This testing framework does not make any assumptions on how your database layer classes work, if they use an ORM like Doctrine, stored procedures or straight SQL. 
-
-The principle is always the same, at some point the code interacts with the data in the DB tables, and we do need to test this.
+Test-Db-Acle aims to take this burden away from the developer. The testing framework does not make any assumptions on how your database layer classes work, if they use an ORM like Doctrine, stored procedures or straight SQL, the principle is always the same, at some point the code interacts with the data in the DB tables, and we do need to test this.
 
+Features
+-------------------
+* Installation via composer
+* disables foreign key checks in database 
+* automatically deals with non-null columns
+* automatically trims date/time columns in mysql when asserting values are in db tables - useful for inserted timestamps (in Sqlite these columns have to be specified)
+* pretty much all components can be exchanged and replaced by custom varieties
+* supports Mysql and Sqlite at present
+* Is framework agnostic, it makes no assumption if ORMs are used for example and should be easily adaptable for other unit test frameworks.
 
-Supported Databases
 -------------------
 
-Supported databases are, at present, MySql and by extension MariaDB.
-I can see Postgres, Sqllite or even Oracle support possible in the future.
+Supported databases are, at present, MySql (and by extension MariaDB) and Sqlite.
+
+The architecture should allow further databases to be added.
 
 Supported Test Frameworks
 -------------------------
 
-This library can be used with PHPUnit as well as other frameworks such as Simpletest (The one that started me on my TDD journey). 
+This library can be used out-of-the-box with PHPUnit. It should be fairly easy to use it with other test frameworks by using the traits provided  and having the 'assertEquals' method delegate to the equivalent method (for example, I remember it being 'assertEqual' in SimpleTest)
 
-I have provided a simple TestDbAcle\PhpUnit\AbstractTestCase, an appropriate Simpletest one would need to be created, but should be as simple as exchanging the parent class.
+I have provided a simple TestDbAcle\PhpUnit\AbstractTestCase as well as \TestDbAcle\PhpUnit\Traits\DatabaseHelperTrait if you are using PHP 5.4 and don't mind using traits.
 
 Introduction and (very) quick example
 -------------------------------------
 
 Ok, to be really fair, testing the database layer is expensive and slooooows down tests, and wherever possible any dependencies on the database should be mocked. But sometimes we just have to do this, hopefully in a well-structured application this can be kept to a minimum.
 
-I was frustrated with the existing tools available. Many had dependencies on particular XUnit frameworks, or I was not  able to use them together with different test base classes as they were difficult to integrate, and all of them were waaaay to verbose and cumbersome to use. 
+There are many tools and approaches available (for example DBUnit or using factory methods in your unit tests) to help with database testing, each with their own strengths, this approach works for me because:
+* I don't have to worry about null columns or foreign key constraints
+* I provide a minimal data set for my tests
+* I can see the test data in a grid-like format above the tests and again when asserting the data in the db.
 
 So I set up my own solution.
 
 ###So how does it work and what does it look like? Show me an example!###
 
-The idea is to use a "pipe-separated-values" (imaginatively called PSV by me) text string to set up test fixtures like this:
+The idea is to use a "pipe-separated-values" text string, let's call it PSV - as in CSV, but with pipes - to set up test fixtures like this:
+
+(The format of the PSV is very similar to the format used by the excellent Behat BDD framework (https://github.com/Behat/Behat))
 
 ```php
 $dbTablesToSetup="
@@ -59,14 +71,18 @@ id |name
 60 |Baz
 
 ";
+//use this if you do not want to use the provided traits or abstract test cases
 $testDbAcle = \TestDbAcle\TestDbAcle::create($pdo);
 $testDbAcle->runCommand(new \TestDbAcle\Commands\SetupTablesCommand($dbTablesToSetup));
+//use this if you extended your test case from \TestDbAcle\PhpUnit\AbstractTestCase or are using the \TestDbAcle\PhpUnit\Traits\DatabaseHelperTrait:
+$this->setupTables($dbTablesToSetup);
 
 ```
 
-Where the framework itself knows which columns are not NULL-able in the table and inserts default values... In fact, the table *table_name* has 30 columns all of which are non-null....
 
-Also, there are various foreign key constraints going on in the background. Test-Db-Acle temporarily disables foreign key checks, so we do not have to worry about this, or in which order we insert the test data.
+The framework itself knows which columns are not NULL-able in the table and inserts default values... In fact, let's assume that the table *table_name* has 30 columns all of which are non-null....
+
+Also, there might be various foreign key constraints going on in the background. Test-Db-Acle temporarily disables foreign key checks, so we do not have to worry about this, or in which order we insert the test data.
 
 ###What about an actual test.....?###
 
@@ -124,11 +140,11 @@ class ExampleTest extends \TestDbAcle\PhpUnit\AbstractTestCase
     }
 }
 ```
-Ok, obviously \Services\AddressService does not exist here (Obviously, it is test-first, right?). The example is quite simple.
+Ok, obviously \Services\AddressService does not exist here (hey, it is test-first, right?) and the example is quite simple.
 
 In real life, I would put the getPdo method into a common base test class for the project and it might be obtained quite differently than here. But, well, this *is* an example.
 
-As you can see, setupTables can set up several tables at once and  assertTableStateContains can verify the state of various tables at the same time, too.
+As you can see, setupTables can set up several tables at once and assertTableStateContains can verify the state of various tables at the same time, too.
 
 Similarly to how setupTables can setup tables that have many more columns than those specified, assertTableStateContains only compares and asserts the values of the columns specified too.
 
@@ -155,7 +171,7 @@ You can also use https://packagist.org/packages/test-db-acle/test-db-acle if you
 
 Contributing
 -------------------------------
-Contributions are more than welcome...!
+Contributions (and criticisms) are more than welcome...!
 
 ###How to run the Test-Db-Acle tests###
 To run the tests, you will need to create an empty database on a MySql sever of your choice, copy tests/Functional/config.php.dist to tests/Functional/config.php and populate with your database details.
@@ -166,3 +182,4 @@ More Documentation
 - [PSV Syntax](docs/PsvParser.md)
 - [AbstractTestCase](docs/AbstractTestCase.md)
 - [Extending and customizing TestDbAcle](docs/Customizing.md)
+- [Changelog](docs/Changelog.md)

docs/Changelog.md

@@ -0,0 +1,5 @@
+What's new
+=================
+
+###0.7###
+Sqlite support has been added and the code base went through another big refactor.

docs/Customizing.md

@@ -5,15 +5,17 @@ All aspects of TestDbAcle can be customised, it uses a very simple ServiceLocato
 The TestDbAcle class is used as a simple facade that provides access to common functionality and all the components involved.
 It is configured in AbstractTestCase::createDatabaseTestHelper and can be customised there.
 
-It is possible to override AbstractTestCase::createDatabaseTestHelper and provide to the TestDbAcle::create factory methods as a second arument a service locator configuration.
-(NB: This service locator is a very simplified version of one inspired by the Zend Framework 2.)
+It is possible to override AbstractTestCase::createDatabaseTestHelper and to provide to the TestDbAcle::create factory method as a second arument a service locator configuration to override the defaults.
+As an optional third parameter a Configuration class can be specified additionally (\FactoriesInterfaceTestDbAcle\Config\FactoriesInterface) where all the default core factories are taken from.
+See \TestDbAcle\Config\DefaultFactories for an example.
 
-The custom configuration is merged with the one provided as the second argument so it is easy to selectively override any part without affecting others.
+
+The custom configuration (2nd argument) is merged with the default configuration so it is relatively easy to selectively exchange any part without affecting others.
 
 The values of the configuration array can either be a string, in which case the class just gets instantiated, or a simple factory that gets the service locator
-as only argument. 
+as the only argument. 
 
-The default configuration is as follows, this can be used as an example for the service locator usage:
+An example configuration is as follows:
 
 ```php
     array(

docs/PsvParser.md

@@ -80,7 +80,7 @@ Whilst it is advisable for readability to line columns up, it is not required fo
 Is equivalent to the above.
 
 ###With table names and expressions###
-This is used in: *TestDbAcle\PhpUnit\AbstractTestCase::setupTables*
+There is a kind of meta-language in the table names, used in: *TestDbAcle\PhpUnit\AbstractTestCase::setupTables* asnd *TestDbAcle\PhpUnit\AbstractTestCase::assertTableStateContains*
 
     [user]
     id  |first_name   |last_name
@@ -104,3 +104,20 @@ It is possible to instead to replace rows:
     20  |stu          |Smith        |value 2
 
 This will not clear the user table but replace any rows with *first_name=john* and *last_name=miller* with the respective specified row.
+
+In Mysql, datetime columns will be automatically truncated in *assertTableStateContains*, for Sqlite, it is possible to indicate which date columns to truncate:
+
+```php
+$this->assertTableStateContains("
+            [address|truncateDates:date_of_entry]
+            address_id  |company    |date_of_entry
+            1           |me         |2001-01-01
+            3           |John       |NULL
+            1000        |them       |NOW
+
+            [user]
+            user_id |name
+            1       |mary
+            ", array('NOW'=>date("Y-m-d")));
+```
+