Trait IntegrationTestTrait

A trait intended to make integration tests of your controllers easier.

This test class provides a number of helper methods and features that make dispatching requests and checking their responses simpler. It favours full integration tests over mock objects as you can test more of your code easily and avoid some of the maintenance pitfalls that mock objects create.

Cake\TestSuite\IntegrationTestTrait uses Cake\Utility\CookieCryptTrait , Cake\View\Helper\SecureFieldTokenTrait

Direct Users

Namespace: Cake\TestSuite
Location: TestSuite/IntegrationTestTrait.php

Properties summary

  • $_appArgs protected
    array|null
    The customized application constructor arguments.
  • $_appClass protected
    string|null
    The customized application class name.
  • $_controller protected
    Cake\Controller\Controller|null
    The controller used in the last request.
  • $_cookie protected
    array
    Cookie data to use in the next request.
  • $_cookieEncryptionKey protected
    null|string
  • $_csrfToken protected
    boolean

    Boolean flag for whether or not the request should have a CSRF token added.

  • $_exception protected
    Exception|null
    The exception being thrown if the case.
  • $_flashMessages protected
    null|array
    Stored flash messages before render
  • $_layoutName protected
    string|null
    The last rendered layout
  • $_request protected
    array
    The data used to build the next request.
  • $_requestSession protected
    Cake\Http\Session|null
    The session instance from the last request
  • $_response protected
    Cake\Http\Response|null
    The response for the most recent request.
  • $_retainFlashMessages protected
    boolean

    Boolean flag for whether or not the request should re-store flash messages

  • $_securityToken protected
    boolean

    Boolean flag for whether or not the request should have a SecurityComponent token added.

  • $_session protected
    array
    Session data to use in the next request.
  • $_useHttpServer protected
    boolean

    Track whether or not tests are run against the PSR7 HTTP stack.

  • $_viewName protected
    string|null
    The last rendered view

Inherited Properties

Method Summary

Method Detail

_addTokens()source protected 

_addTokens( string $url , array $data )

Add the CSRF and Security Component tokens if necessary.

Parameters

string $url
The URL the form is being submitted on.
array $data
The request body data.

Returns

array
The request body with tokens added.

_buildRequest()source protected 

_buildRequest( string|array $url , string $method , string|array|null $data )

Creates a request object with the configured options and parameters.

Parameters

string|array $url
The URL
string $method
The HTTP method
string|array|null $data
The request data.

Returns

array
The request context

_castToString()source protected 

_castToString( array $data )

Recursively casts all data to string as that is how data would be POSTed in the real world

Parameters

array $data
POST data

Returns

array

_getBodyAsString()source protected 

_getBodyAsString( )

Get the response body as string

Returns

string
The response body.

_getCookieEncryptionKey()source protected 

_getCookieEncryptionKey( )

Returns the encryption key to be used.

Returns

string

_handleError()source protected 

_handleError( Exception $exception )

Attempts to render an error response for a given exception.

This method will attempt to use the configured exception renderer. If that class does not exist, the built-in renderer will be used.

Parameters

Exception $exception
Exception to handle.

Throws

Exception

_makeDispatcher()source protected 

_makeDispatcher( )

Get the correct dispatcher instance.

Returns

Cake\TestSuite\MiddlewareDispatcher|Cake\TestSuite\LegacyRequestDispatcher
A dispatcher instance

_sendRequest()source protected 

_sendRequest( string|array $url , string $method , string|array|null $data = [] )

Creates and send the request into a Dispatcher instance.

Receives and stores the response for future inspection.

Parameters

string|array $url
The URL
string $method
The HTTP method
string|array|null $data optional []
The request data.

Throws

PHPUnit\Exception

_url()source protected 

_url( string|array $url )

Creates a valid request url and parameter array more like Request::_url()

Parameters

string|array $url
The URL

Returns

array
Qualified URL, the query parameters, and host data

assertContentType()source public 

assertContentType( string $type , string $message = '' )

Asserts content type

Parameters

string $type
The content-type to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertCookie()source public 

assertCookie( string $expected , string $name , string $message = '' )

Asserts cookie values

Parameters

string $expected
The expected contents.
string $name
The cookie name.
string $message optional ''
The failure message that will be appended to the generated message.

assertCookieEncrypted()source public 

assertCookieEncrypted( string $expected , string $name , string|boolean $encrypt = 'aes' , string|null $key = null , string $message = '' )

Asserts cookie values which are encrypted by the CookieComponent.

The difference from assertCookie() is this decrypts the cookie value like the CookieComponent for this assertion.

Parameters

string $expected
The expected contents.
string $name
The cookie name.
string|boolean $encrypt optional 'aes'
Encryption mode to use.
string|null $key optional null

Encryption key used. Defaults to Security.salt.

string $message optional ''
The failure message that will be appended to the generated message.

See

\Cake\Utility\CookieCryptTrait::_encrypt()

assertCookieNotSet()source public 

assertCookieNotSet( string $cookie , string $message = '' )

Asserts a cookie has not been set in the response

Parameters

string $cookie
The cookie name to check
string $message optional ''
The failure message that will be appended to the generated message.

assertFileResponse()source public 

assertFileResponse( string $expected , string $message = '' )

Asserts that a file with the given name was sent in the response

Parameters

string $expected
The absolute file path that should be sent in the response.
string $message optional ''
The failure message that will be appended to the generated message.

assertFlashElement()source public 

assertFlashElement( string $expected , string $key = 'flash' , string $message = '' )

Asserts a flash element was set

Parameters

string $expected
Expected element name
string $key optional 'flash'
Flash key
string $message optional ''
Assertion failure message

assertFlashElementAt()source public 

assertFlashElementAt( integer $at , string $expected , string $key = 'flash' , string $message = '' )

Asserts a flash element was set at a certain index

Parameters

integer $at
Flash index
string $expected
Expected element name
string $key optional 'flash'
Flash key
string $message optional ''
Assertion failure message

assertFlashMessage()source public 

assertFlashMessage( string $expected , string $key = 'flash' , string $message = '' )

Asserts a flash message was set

Parameters

string $expected
Expected message
string $key optional 'flash'
Flash key
string $message optional ''
Assertion failure message

assertFlashMessageAt()source public 

assertFlashMessageAt( integer $at , string $expected , string $key = 'flash' , string $message = '' )

Asserts a flash message was set at a certain index

Parameters

integer $at
Flash index
string $expected
Expected message
string $key optional 'flash'
Flash key
string $message optional ''
Assertion failure message

assertHeader()source public 

assertHeader( string $header , string $content , string $message = '' )

Asserts response headers

Parameters

string $header
The header to check
string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertHeaderContains()source public 

assertHeaderContains( string $header , string $content , string $message = '' )

Asserts response header contains a string

Parameters

string $header
The header to check
string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertHeaderNotContains()source public 

assertHeaderNotContains( string $header , string $content , string $message = '' )

Asserts response header does not contain a string

Parameters

string $header
The header to check
string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertLayout()source public 

assertLayout( string $content , string $message = '' )

Asserts that the search string was in the layout name.

Parameters

string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertNoRedirect()source public 

assertNoRedirect( string $message = '' )

Asserts that the Location header is not set.

Parameters

string $message optional ''
The failure message that will be appended to the generated message.

assertRedirect()source public 

assertRedirect( string|array|null $url = null , string $message = '' )

Asserts that the Location header is correct.

Parameters

string|array|null $url optional null

The URL you expected the client to go to. This can either be a string URL or an array compatible with Router::url(). Use null to simply check for the existence of this header.

string $message optional ''
The failure message that will be appended to the generated message.

assertRedirectContains()source public 

assertRedirectContains( string $url , string $message = '' )

Asserts that the Location header contains a substring

Parameters

string $url
The URL you expected the client to go to.
string $message optional ''
The failure message that will be appended to the generated message.

assertRedirectNotContains()source public 

assertRedirectNotContains( string $url , string $message = '' )

Asserts that the Location header does not contain a substring

Parameters

string $url
The URL you expected the client to go to.
string $message optional ''
The failure message that will be appended to the generated message.

assertResponseCode()source public 

assertResponseCode( integer $code , string $message = null )

Asserts a specific response status code.

Parameters

integer $code
Status code to assert.
string $message optional null
Custom message for failure.

assertResponseContains()source public 

assertResponseContains( string $content , string $message = '' , boolean $ignoreCase = false )

Asserts content exists in the response body.

Parameters

string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.
boolean $ignoreCase optional false
A flag to check whether we should ignore case or not.

assertResponseEmpty()source public 

assertResponseEmpty( string $message = '' )

Assert response content is empty.

Parameters

string $message optional ''
The failure message that will be appended to the generated message.

assertResponseEquals()source public 

assertResponseEquals( mixed $content , string $message = '' )

Asserts content in the response body equals.

Parameters

mixed $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertResponseError()source public 

assertResponseError( string $message = null )

Asserts that the response status code is in the 4xx range.

Parameters

string $message optional null
Custom message for failure.

assertResponseFailure()source public 

assertResponseFailure( string $message = null )

Asserts that the response status code is in the 5xx range.

Parameters

string $message optional null
Custom message for failure.

assertResponseNotContains()source public 

assertResponseNotContains( string $content , string $message = '' , boolean $ignoreCase = false )

Asserts content does not exist in the response body.

Parameters

string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.
boolean $ignoreCase optional false
A flag to check whether we should ignore case or not.

assertResponseNotEmpty()source public 

assertResponseNotEmpty( string $message = '' )

Assert response content is not empty.

Parameters

string $message optional ''
The failure message that will be appended to the generated message.

assertResponseNotEquals()source public 

assertResponseNotEquals( mixed $content , string $message = '' )

Asserts content in the response body not equals.

Parameters

mixed $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

assertResponseNotRegExp()source public 

assertResponseNotRegExp( string $pattern , string $message = '' )

Asserts that the response body does not match a given regular expression.

Parameters

string $pattern
The pattern to compare against.
string $message optional ''
The failure message that will be appended to the generated message.

assertResponseOk()source public 

assertResponseOk( string $message = null )

Asserts that the response status code is in the 2xx range.

Parameters

string $message optional null
Custom message for failure.

assertResponseRegExp()source public 

assertResponseRegExp( string $pattern , string $message = '' )

Asserts that the response body matches a given regular expression.

Parameters

string $pattern
The pattern to compare against.
string $message optional ''
The failure message that will be appended to the generated message.

assertResponseSuccess()source public 

assertResponseSuccess( string $message = null )

Asserts that the response status code is in the 2xx/3xx range.

Parameters

string $message optional null
Custom message for failure.

assertSession()source public 

assertSession( string $expected , string $path , string $message = '' )

Asserts session contents

Parameters

string $expected
The expected contents.
string $path
The session data path. Uses Hash::get() compatible notation
string $message optional ''
The failure message that will be appended to the generated message.

assertTemplate()source public 

assertTemplate( string $content , string $message = '' )

Asserts that the search string was in the template name.

Parameters

string $content
The content to check for.
string $message optional ''
The failure message that will be appended to the generated message.

cleanup()source public 

cleanup( )

Clears the state used for requests.

After

configApplication()source public 

configApplication( string $class , array|null $constructorArgs )

Configure the application class to use in integration tests.

Combined with useHttpServer() to customize the class name and constructor arguments of your application class.

Parameters

string $class
The application class name.
array|null $constructorArgs
The constructor arguments for your application class.

configRequest()source public 

configRequest( array $data )

Configures the data for the next request.

This data is cleared in the tearDown() method.

You can call this method multiple times to append into the current state.

Parameters

array $data
The request data to use.

controllerSpy()source public 

controllerSpy( Cake\Event\Event $event , Cake\Controller\Controller|null $controller = null )

Adds additional event spies to the controller/view event manager.

Parameters

Cake\Event\Event $event
A dispatcher event.
Cake\Controller\Controller|null $controller optional null
Controller instance.

cookie()source public 

cookie( string $name , mixed $value )

Sets a request cookie for future requests.

This method lets you configure the session data you want to be used for requests that follow. The session state is reset in each tearDown().

You can call this method multiple times to append into the current state.

Parameters

string $name
The cookie name to use.
mixed $value
The value of the cookie.

cookieEncrypted()source public 

cookieEncrypted( string $name , mixed $value , string|boolean $encrypt = 'aes' , string|null $key = null )

Sets a encrypted request cookie for future requests.

The difference from cookie() is this encrypts the cookie value like the CookieComponent.

Parameters

string $name
The cookie name to use.
mixed $value
The value of the cookie.
string|boolean $encrypt optional 'aes'
Encryption mode to use.
string|null $key optional null

Encryption key used. Defaults to Security.salt.

See

\Cake\Utility\CookieCryptTrait::_encrypt()

delete()source public 

delete( string|array $url )

Performs a DELETE request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.

Throws

PHPUnit\Exception

disableErrorHandlerMiddleware()source public 

disableErrorHandlerMiddleware( )

Disable the error handler middleware.

By using this function, exceptions are no longer caught by the ErrorHandlerMiddleware and are instead re-thrown by the TestExceptionRenderer. This can be helpful when trying to diagnose/debug unexpected failures in test cases.

enableCsrfToken()source public 

enableCsrfToken( )

Calling this method will add a CSRF token to the request.

Both the POST data and cookie will be populated when this option is enabled. The default parameter names will be used.

enableRetainFlashMessages()source public 

enableRetainFlashMessages( )

Calling this method will re-store flash messages into the test session after being removed by the FlashHelper

enableSecurityToken()source public 

enableSecurityToken( )

Calling this method will enable a SecurityComponent compatible token to be added to request data. This lets you easily test actions protected by SecurityComponent.

extractExceptionMessage()source protected 

extractExceptionMessage( Exception $exception )

Extract verbose message for existing exception

Parameters

Exception $exception
Exception to extract

Returns

string

extractVerboseMessage()source protected 

extractVerboseMessage( string $message = null )

Inspect controller to extract possible causes of the failed assertion

Parameters

string $message optional null
Original message to use as a base

Returns

null|string

get()source public 

get( string|array $url )

Performs a GET request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.

Throws

PHPUnit\Exception

head()source public 

head( string|array $url )

Performs a HEAD request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.

Throws

PHPUnit\Exception

options()source public 

options( string|array $url )

Performs an OPTIONS request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.

Throws

PHPUnit\Exception

patch()source public 

patch( string|array $url , string|array|null $data = [] )

Performs a PATCH request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.
string|array|null $data optional []
The data for the request.

Throws

PHPUnit\Exception

post()source public 

post( string|array $url , string|array|null $data = [] )

Performs a POST request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.
string|array|null $data optional []
The data for the request.

Throws

PHPUnit\Exception

put()source public 

put( string|array $url , string|array|null $data = [] )

Performs a PUT request using the current request data.

The response of the dispatched request will be stored as a property. You can use various assert methods to check the response.

Parameters

string|array $url
The URL to request.
string|array|null $data optional []
The data for the request.

Throws

PHPUnit\Exception

session()source public 

session( array $data )

Sets session data.

This method lets you configure the session data you want to be used for requests that follow. The session state is reset in each tearDown().

You can call this method multiple times to append into the current state.

Parameters

array $data
The session data to use.

setupServer()source public 

setupServer( )

Auto-detect if the HTTP middleware stack should be used.

Before

useHttpServer()source public 

useHttpServer( boolean $enable )

Toggle whether or not you want to use the HTTP Server stack.

Parameters

boolean $enable
Enable/disable the usage of the HTTP Stack.

viewVariable()source public 

viewVariable( string $name )

Fetches a view variable by name.

If the view variable does not exist, null will be returned.

Parameters

string $name
The view variable to get.

Returns

mixed
The view variable if set.

Methods used from Cake\Utility\CookieCryptTrait

_checkCipher()source protected 

_checkCipher( string $encrypt )

Helper method for validating encryption cipher names.

Parameters

string $encrypt
The cipher name.

Throws

RuntimeException
When an invalid cipher is provided.

_decode()source protected 

_decode( string $value , string|false $encrypt , string|null $key )

Decodes and decrypts a single value.

Parameters

string $value
The value to decode & decrypt.
string|false $encrypt
The encryption cipher to use.
string|null $key
Used as the security salt if specified.

Returns

string|array
Decoded values.

_decrypt()source protected 

_decrypt( array $values , string|boolean $mode , string|null $key = null )

Decrypts $value using public $type method in Security class

Parameters

array $values
Values to decrypt
string|boolean $mode
Encryption mode
string|null $key optional null
Used as the security salt if specified.

Returns

string|array
Decrypted values

_encrypt()source protected 

_encrypt( string $value , string|boolean $encrypt , string|null $key = null )

Encrypts $value using public $type method in Security class

Parameters

string $value
Value to encrypt
string|boolean $encrypt

Encryption mode to use. False disabled encryption.

string|null $key optional null
Used as the security salt if specified.

Returns

string
Encoded values

_explode()source protected 

_explode( string $string )

Explode method to return array from string set in CookieComponent::_implode() Maintains reading backwards compatibility with 1.x CookieComponent::_implode().

Parameters

string $string
A string containing JSON encoded data, or a bare string.

Returns

string|array
Map of key and values

_implode()source protected 

_implode( array $array )

Implode method to keep keys are multidimensional arrays

Parameters

array $array
Map of key and values

Returns

string
A json encoded string.

Methods used from Cake\View\Helper\SecureFieldTokenTrait

_buildFieldToken()source protected 

_buildFieldToken( string $url , array $fields , array $unlockedFields = [] )

Generate the token data for the provided inputs.

Parameters

string $url
The URL the form is being submitted to.
array $fields

If set specifies the list of fields to use when generating the hash.

array $unlockedFields optional []

The list of fields that are excluded from field validation.

Returns

array
The token data.

Properties detail

$_appArgssource

protected array|null

The customized application constructor arguments.

$_appClasssource

protected string|null

The customized application class name.

$_controllersource

protected Cake\Controller\Controller|null

The controller used in the last request.

protected array

Cookie data to use in the next request.

[]

$_cookieEncryptionKeysource

protected null|string

$_csrfTokensource

protected boolean

Boolean flag for whether or not the request should have a CSRF token added.

false

$_exceptionsource

protected Exception|null

The exception being thrown if the case.

$_flashMessagessource

protected null|array

Stored flash messages before render

$_layoutNamesource

protected string|null

The last rendered layout

$_requestsource

protected array

The data used to build the next request.

[]

$_requestSessionsource

protected Cake\Http\Session|null

The session instance from the last request

$_responsesource

protected Cake\Http\Response|null

The response for the most recent request.

$_retainFlashMessagessource

protected boolean

Boolean flag for whether or not the request should re-store flash messages

false

$_securityTokensource

protected boolean

Boolean flag for whether or not the request should have a SecurityComponent token added.

false

$_sessionsource

protected array

Session data to use in the next request.

[]

$_useHttpServersource

protected boolean

Track whether or not tests are run against the PSR7 HTTP stack.

false

$_viewNamesource

protected string|null

The last rendered view

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/3.7/class-Cake.TestSuite.IntegrationTestTrait.html