Usage.md

Usage

The DataValidationTestTrait provides helper methods to simplify testing the data validation configuration of your CakePHP tables.

Setup

Add the trait to any PHPUnit test case:

<?php
declare(strict_types=1);

namespace App\Test\TestCase\Model\Table;

use Cake\TestSuite\TestCase;
use DataValidationTesting\Traits\DataValidationTestTrait;

class ArticlesTableTest extends TestCase
{
    use DataValidationTestTrait;

    private \App\Model\Table\ArticlesTable $Articles;

    protected function setUp(): void
    {
        parent::setUp();
        $this->Articles = $this->getTableLocator()->get('Articles');
    }
}

All helper methods are protected and callable from within your test class.

Example

public function assertValidationTitle(): void
{
    // Assert that the "title" field's presence is required
    $this->assertValidationRequired($this->Articles, 'title');
    // Assert that the field "title" cannot be empty
    $this->assertValidationNotEmpty($this->Articles, 'title');
    // Assert that the "title" field's maximum length is 255 characters
    $this->assertValidationMaxLength($this->Articles, 'title', 255);
}

public function assertValidationIsPublished(): void
{
    // Assert that the field "is_published" must have a boolean value
    $this->assertValidationBoolean($this->Articles, 'is_published');
}

Each helper builds an entity, runs the validator, and asserts the expected errors (or absence of errors) on the given field.

Available methods

Note: The presence, emptiness and type helpers listed below are rule-dedicated: each one only asserts that its own validation rule is (or is not) configured for the given field and ignores any other validation errors present on that field. They no longer compare against the field's full error list.

Presence and emptiness

• assertValidationRequired($table, $fieldName) - asserts the field is configured to require presence (_required).
• assertValidationNotRequired($table, $fieldName) - asserts the field is not configured to require presence.
• assertValidationNotEmpty($table, $fieldName) - asserts the field is configured to disallow empty values, i.e. null or '' (_empty).
• assertValidationEmpty($table, $fieldName) - asserts the field is configured to allow empty values, i.e. null or ''.

Type validators

• assertValidationBoolean($table, $fieldName) - asserts the field is configured with the boolean validation rule.
• assertValidationURLWithProtocol($table, $fieldName) - asserts the field is configured with the urlWithProtocol validation rule (requires http:// or https://).
• assertValidationDateTime($table, $fieldName) - asserts the field is configured with the dateTime validation rule.
• assertValidationDate($table, $fieldName) - asserts the field is configured with the date validation rule.
• assertValidationNaturalNumber($table, $fieldName) - asserts the field is configured with the naturalNumber validation rule (positive integers).
• assertValidationScalar($table, $fieldName) - asserts the field is configured with the scalar validation rule.
• assertValidationDecimal($table, $fieldName) - asserts the field is configured with the decimal validation rule.
• assertValidationInteger($table, $fieldName) - asserts the field is configured with the integer validation rule.
• assertValidationNonNegativeInteger($table, $fieldName) - asserts the field is configured with the nonNegativeInteger validation rule.
• assertValidationGreaterThanOrEqual($table, $fieldName, $threshold) - asserts the field is configured with the greaterThanOrEqual validation rule.
• assertValidationEmail($table, $fieldName) - asserts the field is configured with the email validation rule.
• assertValidationUuid($table, $fieldName) - asserts the field is configured with the uuid validation rule.

Length validators

• assertValidationMaxLength($table, $fieldName, $maxLength)
• assertValidationMinLength($table, $fieldName, $minLength, $expected)
• assertValidationLengthBetween($table, $fieldName, $minLength, $maxLength)
• assertValidationRange($table, $fieldName, $lowerBound, $upperBound)

Generic helpers

• assertValidation($table, $fieldName, $dataSet, $expected) - the underlying helper. Use when no specialized helper fits. Compares the field's complete error array against $expected.
• assertValidationContains($table, $fieldName, $dataSet, $expected) - asserts the given "rule name" => "message" pairs are present on the field, ignoring any other errors.
• assertValidationNotContains($table, $fieldName, $dataSet, $rules) - asserts the given rule names are not present on the field, ignoring any other errors.
• assertValidationNoErrors($table, $fieldName, $dataSet) - asserts a data set produces no errors on the field.
• assertValidationInList($table, $list, $fieldName, $expected) - runs the complete-error-array assertion for each value in a list.
• assertValidationInListContains($table, $list, $fieldName, $expected) - runs the contains assertion for each value in a list.
• assertValidationInListNotContains($table, $list, $fieldName, $rules) - runs the not contains assertion for each value in a list.
• assertValidationTableErrors($table, $dataSet, $expected) - asserts errors across all fields.
• assertValidationTableNoErrors($table, $dataSet) - asserts a full data set produces no errors at all.

Rules helpers

For application rules that run at save time (not marshalling time). These require a real database connection and fixtures.

• assertRulesNoErrors($table, $fieldName, $dataSet)
• assertRules($table, $fieldName, $dataSet, $expected)
• assertValidationUnique($table, $fieldName, $fieldValue)
• assertValidationForeignKey($table, $fieldName)

Dependent fields

Use the $additionalDataSet parameter to supply required companion fields so your test only fails for the reason you care about:

$this->assertValidationNotEmpty(
    $this->Articles,
    'title',
    ['author_id' => 1]
);

Passing newEntity() options

The $options parameter is forwarded to Table::newEntity():

$this->assertValidationRequired(
    $this->Articles,
    'title',
    [],
    ['validate' => 'create']
);