Skip to content

Commit

Permalink
Fixed #286 - Added cookbook article about the new test suite.
Browse files Browse the repository at this point in the history
Fixed some small issue with non-existing pages in the left documentation navigation and the style with strong elements.
  • Loading branch information
Marc J. Schmidt committed Aug 1, 2014
1 parent d9bbbc2 commit 1395c56
Show file tree
Hide file tree
Showing 6 changed files with 349 additions and 112 deletions.
6 changes: 3 additions & 3 deletions _config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ documentation:
- title: Active Query Classes
url: /documentation/reference/model-criteria.html
- title: Build Properties
url: /documentation/documentation/reference/buildtime-configuration.html
url: /documentation/reference/buildtime-configuration.html
- title: Runtime Configuration File
url: /documentation/reference/runtime-configuration.html
- title: Compatibility index
Expand Down Expand Up @@ -88,6 +88,8 @@ documentation:
url: /documentation/cookbook/user-contributed-behaviors.html

- title: Cookbook
- title: Working With Propel's Test Suite
url: /documentation/cookbook/working-with-test-suite.html
- title: Additional SQL Files
url: /documentation/cookbook/adding-additional-sql-files.html
- title: Advanced Column Types
Expand Down Expand Up @@ -118,7 +120,5 @@ documentation:
url: /documentation/cookbook/writing-behavior.html
- title: Testing Your Behaviors
url: /documentation/cookbook/testing-your-behaviors.html
- title: Working with unit tests
url: /documentation/cookbook/working-with-unit-tests.html
- title: Working with Silex
url: /documentation/cookbook/silex/working-with-silex.html
107 changes: 3 additions & 104 deletions contribute.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -65,110 +65,9 @@ button. Add a short description to this Pull Request and submit it.

## Running Unit Tests ##

Propel uses [PHPUnit][] to test the build and runtime frameworks.

You can find the unit test classes and support files in the `tests/` directory.

### Install Composer ###

In order to run the tests, you must install the development dependencies. Propel
uses [Composer][] to manage its dependencies. To install it, you are done with:

$ wget http://getcomposer.org/composer.phar

Or if you don't have `wget` on your machine:

$ curl -s http://getcomposer.org/installer | php

Then run Composer to install the necessary stuff:

$ php composer.phar install

#### Setup MySQL ####

The Propel test suite requires a database (`test` for instance, but feel free to
choose the name you want), and three database schemas: `bookstore_schemas`,
`contest`, and `second_hand_books`.

Here is the set of commands to run in order to setup MySQL:

$ mysql -uroot -e 'SET FOREIGN_KEY_CHECKS = 0; DROP DATABASE IF EXISTS test; DROP SCHEMA IF EXISTS second_hand_books; DROP SCHEMA IF EXISTS contest; DROP SCHEMA IF EXISTS bookstore_schemas; SET FOREIGN_KEY_CHECKS = 1;'
$ mysql -uroot -e 'CREATE DATABASE migration; CREATE DATABASE test; CREATE SCHEMA bookstore_schemas; CREATE SCHEMA contest; CREATE SCHEMA second_hand_books;'

Once done, build fixtures (default vendor is `mysql`):

$ bin/propel test:prepare

To match Travis CI MySQL configuration, you must set `@@sql_mode` to `STRICT_ALL_TABLES` in yours.

#### Configure PostgreSQL ####

Create mandatory databases, then run:

$ bin/propel test:prepare --vendor=pgsql --dsn="pgsql:dbname=test" --user="postgres"

#### For SQLite ####

There is nothing to setup, just run:

$ bin/propel test:prepare --vendor=sqlite --dsn="sqlite:/tmp/database.sqlite"

Now you can run the test suite by running:

$ ./vendor/bin/phpunit

### How the Tests Work ###

Every method in the test classes that begins with 'test' is run as a test case by PHPUnit. All tests are run in isolation; the `setUp()` method is called at the beginning of ''each'' test and the `tearDown()` method is called at the end.

The `BookstoreTestBase` class specifies `setUp()` and `tearDown()` methods which populate and depopulate, respectively, the database. This means that every unit test is run with a cleanly populated database. To see the sample data that is populated, take a look at the `BookstoreDataPopulator` class. You can also add data to this class, if needed by your tests; however, proceed cautiously when changing existing data in there as there may be unit tests that depend on it. More typically, you can simply create the data you need from within your test method. It will be deleted by the `tearDown()` method, so no need to clean up after yourself.

## Writing Tests ##

If you've made a change to a template or to Propel behavior, the right thing to do is write a unit test that ensures that it works properly -- and continues to work in the future.

Writing a unit test often means adding a method to one of the existing test classes. For example, let's test a feature in the Propel templates that supports saving of objects when only default values have been specified. Just add a `testSaveWithDefaultValues()` method to the `GeneratedObjectTest` class, as follows:

```php
<?php

/**
* Test saving object when only default values are set.
*/
public function testSaveWithDefaultValues() {

// Relies on a default value of 'Penguin' specified in schema
// for publisher.name col.

$pub = new Publisher();
$pub->setName('Penguin');
// in the past this wouldn't have marked object as modified
// since 'Penguin' is the value that's already set for that attrib
$pub->save();

// if getId() returns the new ID, then we know save() worked.
$this->assertNotNull($pub->getId(), "Expect Publisher->save() to work with only default values.");
}
?>
```

Run the test again using the command line to check that it passes:

$ ./vendor/bin/phpunit GeneratedObjectTest


You can also write additional unit test classes to any of the directories in `test/testsuite/` (or add new directories if needed). The `./vendor/bin/phpunit` command will find these files automatically and run them.

## Fix checkstyle ##

You can fix checkstyle __before to create your commit__ by using the Symfony2
[php-cs-fixer][] script. You just need to install the script:

$ wget http://cs.sensiolabs.org/get/php-cs-fixer.phar

Then use it on the file you have edited:

$ php php-cs-fixer.phar fix $(git ls-files -m)
Please make sure our test suite is still green and you wrote a adequate test that covers your changes.

You can get more information in our cookbook article: [Working with Propel's Test Suite](/documentation/cookbook/working-with-test-suite.html).

## Improve the documentation ##

Expand Down
4 changes: 0 additions & 4 deletions css/markdown.css
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,6 @@
font-style: italic;
}

.markdown strong {
font-weight: bold;
}

.markdown ul {
margin: 0;
padding: 0;
Expand Down
Loading

0 comments on commit 1395c56

Please sign in to comment.