Skip to content

Commit

Permalink
Updated docs for 1.4.x
Browse files Browse the repository at this point in the history
  • Loading branch information
@TavoNiievez
TavoNiievez committed Aug 27, 2020
1 parent 9848be0 commit 17ae6d4
Show file tree
Hide file tree
Showing 3 changed files with 102 additions and 77 deletions.
25 changes: 18 additions & 7 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Changelog

## 1.4

* Added **_Fluent Interface_** support, this allows you to add `it`'s and `should`'s chained to a `specify` or `describe`.
* `Specify.php` trait now only has the public API methods.
* If an `it` or `should` only receives text now that test is marked as incomplete.
* `shouldNot` and `its` were added as aliases.
* Added `.phpunit.result.cache` file to `.gitignore`
* Updated `README.md`

## 1.0

* BREAKING: PHPUnit 6 support
Expand All @@ -15,32 +24,34 @@
3. If relied on property cloning, add `@specify` annotation for all properties which needs to be cloned for specify blocks
4. If you used `throws` parameter, consider using [AssertThrows](https://github.com/Codeception/AssertThrows) package.

#### 0.4.3
## 0.4.3

* Show example index on failure by @zszucs *2015-11-27*


#### 0.4.2
## 0.4.2

* Testing exception messages by @chrismichaels84 https://github.com/Codeception/Specify#exceptions

#### 0.4.0
## 0.4.0

* Fixes cloning properties in examples. Issue #6 *2014-10-15*
* Added global and local specify configs, for disabling cloning properties and changing cloning methods *2014-10-15*


#### 0.3.6 03/22/2014

## 0.3.6
#### 03/22/2014
* Cloning unclonnable items


#### 0.3.5 03/22/2014
## 0.3.5
#### 03/22/2014

* Updated to DeepCopy 1.1.0


#### 0.3.4 02/23/2014
## 0.3.4
#### 02/23/2014

* Added DeepCopy library to save/restore objects between specs
* Robo file for releases
2 changes: 1 addition & 1 deletion LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
The MIT License (MIT)

Copyright (c) 2013 Codeception PHP Testing Framework
Copyright (c) 2013-2020 Codeception PHP Testing Framework

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
Expand Down
152 changes: 83 additions & 69 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,30 @@
Specify
=======

BDD style code blocks for PHPUnit / Codeception
BDD style code blocks for [PHPUnit][1] or [Codeception][2]

[![Latest Stable Version](https://poser.pugx.org/codeception/specify/v/stable)](https://packagist.org/packages/codeception/specify)[![Total Downloads](https://poser.pugx.org/codeception/specify/downloads)](https://packagist.org/packages/codeception/specify)[![Latest Unstable Version](https://poser.pugx.org/codeception/specify/v/unstable)](https://packagist.org/packages/codeception/specify)[![License](https://poser.pugx.org/codeception/specify/license)](https://packagist.org/packages/codeception/specify)
[![Latest Stable Version](https://poser.pugx.org/codeception/specify/v/stable)](https://packagist.org/packages/codeception/specify)
[![Total Downloads](https://poser.pugx.org/codeception/specify/downloads)](https://packagist.org/packages/codeception/specify)
[![Latest Unstable Version](https://poser.pugx.org/codeception/specify/v/unstable)](https://packagist.org/packages/codeception/specify)
[![License](https://poser.pugx.org/codeception/specify/license)](https://packagist.org/packages/codeception/specify)

Specify allows you to write your tests in more readable BDD style, the same way you might have experienced with [Jasmine](https://jasmine.github.io/).
Specify allows you to write your tests in more readable BDD style, the same way you might have experienced with [Jasmine][3].
Inspired by MiniTest of Ruby now you combine BDD and classical TDD style in one test.

### Basic Example
## Installation

*Requires PHP >= 7.1*

* Install with Composer:

```
composer require codeception/specify --dev
```

* Include `Codeception\Specify` trait in your tests.


## Usage

Specify `$this->specify` method to add isolated test blocks for your PHPUnit tests!

Expand All @@ -17,75 +33,65 @@ public function testValidation()
{
$this->assertInstanceOf('Model', $this->user);

$this->specify("username is required", function() {
$this->specify('username is required', function() {
$this->user->username = null;
$this->assertFalse($this->user->validate(['username']));
$this->assertFalse($this->user->validate(['username']));
});

$this->specify("username is too long", function() {
$this->specify('username is too long', function() {
$this->user->username = 'toolooooongnaaaaaaameeee';
$this->assertFalse($this->user->validate(['username']));
});

$this->specify("username is ok", function() {
$this->user->username = 'davert';
$this->assertTrue($this->user->validate(['username']));
$this->assertFalse($this->user->validate(['username']));
});
}
```

### BDD Example

Specify supports `describe-it` BDD syntax inside PHPUnit
Specify supports `describe-it` and `describe-should` BDD syntax inside PHPUnit

```php
public function testValidation()
{
$this->describe("user", function() {
$this->it("should have a name", function() {
$this->describe('user', function () {
$this->it('should have a name', function() {
$this->user->username = null;
$this->assertFalse($this->user->validate(['username']));
$this->assertFalse($this->user->validate(['username']));
});
});

$this->it("should not have long name", function() {
$this->user->username = 'toolooooongnaaaaaaameeee';
$this->assertFalse($this->user->validate(['username']));
});

// use `$this->>should` as shortcut
$this->should("be ok with valid name", function() {
// you can use chained methods for better readability:
$this->describe('user')
->should('be ok with valid name', function() {
$this->user->username = 'davert';
$this->assertTrue($this->user->validate(['username']));
});

$this->assertTrue($this->user->validate(['username']));
})
->shouldNot('have long name', function() {
$this->user->username = 'toolooooongnaaaaaaameeee';
$this->assertFalse($this->user->validate(['username']));
})
// empty codeblocks are marked as Incomplete tests
$this->it("should be ok with valid name");
});
->it('should be ok with valid name')
;
}
```


### Specify + Verify Example

Use [Codeception/Verify](https://github.com/Codeception/Verify) for simpler assertions:
Use [Codeception/Verify][4] for simpler assertions:

```php
public function testValidation()
{
$this->specify("username is required", function() {
$this->user->username = null;
expect_not($this->user->validate(['username']));
});

$this->specify("username is too long", function() {
$this->specify('username is too long', function() {
$this->user->username = 'toolooooongnaaaaaaameeee';
expect_not($this->user->validate(['username']));
expect_not($this->user->validate(['username']));
});

$this->specify('username is ok', function() {
$this->user->username = 'davert';
expect_that($this->user->validate(['username']));
});

$this->specify("username is ok", function() {
$this->user->username = 'davert';
expect_that($this->user->validate(['username']));
});
}
```

Expand All @@ -98,26 +104,27 @@ This is very similar to BDD syntax as in RSpec or Mocha but works inside PHPUnit

```php
<?php

class UserTest extends PHPUnit\Framework\TestCase
{
use Codeception\Specify;

/** @specify */
protected $user; // is cloned inside specify blocks
public function setUp()

public function setUp(): void
{
$this->user = new User;
}

public function testValidation()
{
$this->user->name = 'davert';
$this->specify("i can change my name", function() {
$this->specify('i can change my name', function() {
$this->user->name = 'jon';
$this->assertEquals('jon', $this->user->name);
});
// user name is "davert" again
});
// user name is 'davert' again
$this->assertEquals('davert', $this->user->name);
}
}
Expand All @@ -130,7 +137,7 @@ Failure in `specify` block won't get your test stopped.

```php
<?php
$this->specify("failing but test goes on", function() {
$this->specify('failing but test goes on', function() {
$this->fail('bye');
});
$this->assertTrue(true);
Expand Down Expand Up @@ -186,7 +193,7 @@ $this->specify('this should not fail', function () {

```php
<?php
$this->specify("should calculate square numbers", function($number, $square) {
$this->specify('should calculate square numbers', function($number, $square) {
$this->assertEquals($square, $number*$number);
}, ['examples' => [
[2,4],
Expand All @@ -198,7 +205,7 @@ You can also use DataProvider functions in `examples` param.

```php
<?php
$this->specify("should calculate square numbers", function($number, $square) {
$this->specify('should calculate square numbers', function($number, $square) {
$this->assertEquals($square, $number*$number);
}, ['examples' => $this->provider()]);
```
Expand Down Expand Up @@ -243,26 +250,25 @@ $this->cleanSpecify(); // removes before/after callbacks

Available methods:

* `$this->specify(name, callable fn = null, params = [])` - starts a specify code block. If `fn` is null, marks test as incomplete.
* `$this->describe(name, callable fn = null)` - starts a describe code block. Same as `specify` but expects to receive more nested into `fn`.
* `$this->it(name, callable fn = null)` - starts a code block. Alias to `specify`.
* `$this->should(name, callable fn = null)` - starts a code block. Same as `specify` but prepends word "should" into description.
```php
// Starts a specify code block:
$this->specify(string $thing, callable $code = null, $examples = [])

// Starts a describe code block. Same as 'specify' but expects chained 'it' or 'should' methods.
$this->describe(string $feature, callable $code = null)

## Installation
// Starts a code block. If 'code' is null, marks test as incomplete.
$this->it(string $spec, callable $code = null, $examples = [])
$this->its(string $spec, callable $code = null, $examples = [])

*Requires PHP >= 7.*

* Install with Composer:

```
composer require codeception/specify --dev
// Starts a code block. Same as 'it' but prepends 'should' or 'should not' into description.
$this->should(string $behavior, callable $code = null, $examples = [])
$this->shouldNot(string $behavior, callable $code = null, $examples = [])
```

* Include `Codeception\Specify` trait into `PHPUnit\Framework\TestCase`.
* Add `/** @specify **/` docblock for all properties you want to make isolated inside tests.
## Printer Options

* For PHPUnit add `Codeception\Specify\ResultPrinter` printer into `phpunit.xml`
For PHPUnit, add `Codeception\Specify\ResultPrinter` printer into `phpunit.xml`

```xml
<phpunit colors="true" printerClass="Codeception\Specify\ResultPrinter">
Expand All @@ -271,8 +277,16 @@ composer require codeception/specify --dev

## Recommended

* Use [Codeception/AssertThrows](https://github.com/Codeception/AssertThrows) for exception assertions
* Use [Codeception/DomainAssert](https://github.com/Codeception/DomainAssert) for verbose domain logic assertions
* Сombine this with [Codeception/Verify](https://github.com/Codeception/Verify) library, to get BDD style assertions.
* Use [Codeception/AssertThrows][5] for exception assertions
* Use [Codeception/DomainAssert][6] for verbose domain logic assertions
* Combine this with [Codeception/Verify][4] library, to get BDD style assertions.

License: [MIT.][7]

License: MIT
[1]: https://phpunit.de/
[2]: http://codeception.com/
[3]: https://jasmine.github.io/
[4]: https://github.com/Codeception/Verify
[5]: https://github.com/Codeception/AssertThrows
[6]: https://github.com/Codeception/DomainAssert
[7]: /LICENSE

0 comments on commit 17ae6d4

Please sign in to comment.