Assertions

[roxblnfk]

• assertSame Add Assert::same and assertion collector #3
• assertException Expose ExpectException functionality #4 Asser::exception supports objects #5
• assertNotSame feat(assert): Add Assert::notSame #8
• assertTrue/false feat(assert): Add Assert::true #11
• instanceOf feat(assert): add Assert::instanceOf #14
• assertContains feat(assert): add Assert::contains #16
• Assert::leaks(...object) Expose Assert::leaks() #15
• Assert::blank() feat(assert): add Assert::blank() method #43
• Assert::equals feat(assert): add Assert:equal(), Assert::notEqual() and fix default compare message #27
• Assert::fail Add Assert::fail #26
• Assert::string feat(assert): add Assert::string(), Assert::string()->contains() methods #45
• feat(assert): add Assert::int() with greaterThan and greaterThanOrEqual #48
• feat(assert): add Assert::float, numeric lessThan and lessThanOrEqual #49
• Drafting Assert API #50
• feat(assert): add new assert Interfaces and methods for data types #51
• feat(assert): implement AssertIterable methods #55

[petrdobr]

(continuing from this discussion)
I think blank() function is a good idea. It will already be familiar to Laravel users and won’t be confused with PHP's empty() function.
And I think adding assertion of empty Countables will be a good enhancement (after all, as far as I know Laravel collections are countable too).
So instead of empty I will try to add Assert::blank(mixed $value).

The copy of php doc comment + countables

/**
 * Checks if a value is blank.
 * 
 * Returns true only for values representing absence of data:
 * null, empty string, empty array or countable object with no elements.
 * 
 * Unlike empty(), does not consider false, 0, and "0" as blank,
 * since they represent valid data.
 * 
 * @param mixed $value The value to check
 * @return bool true if value is null, "" or [], false otherwise
 */
function blank(mixed $value): bool
{
    // ...
}

[petrdobr]

Assert todo list

Equality & Comparison

• equals(mixed $expected, mixed $actual) - assert values are equal, not strict comparison ==.
• notEquals(mixed $expected, mixed $actual) - assert values are not equal, not strict comparison ==.
• greaterThan($min, $actual) / greaterThanOrEqual($min, $actual)
  Numeric comparisons for metrics, lengths, counters.
• lessThan($max, $actual) / lessThanOrEqual($max, $actual)
  Symmetric bound checks.

Arrays & Iterables

• count(int $expected, array|\Countable $value)
  Assert collection size (materialize if needed).
• arrayHasKey(string|int $key, array|ArrayAccess $array) / arrayNotHasKey(...)
  Structure/shape checks for maps.

Strings

• stringContains(string $needle, string $haystack) / stringNotContains(...)
  Substring presence (case-sensitive by default).
• stringStartsWith(string $prefix, string $haystack) / stringEndsWith(string $suffix, string $haystack)
  Quick prefix/suffix checks.

Types & State

• array(mixed $value) / string(...) / int(...) / float(...) / bool(...)
  Primitive type guards (useful in data providers).
• blank(mixed $value) / notBlank(mixed $value)
  See actual checks in the comment above.

JSON

• json(string $value)
  Valid JSON (decodes without error).
• jsonEquals(string|array|object $expected, string|array|object $actual, bool $canonicalize = true)
  Compare after decode + normalized ordering (keys).

Filesystem

• fileExists(string $path) / fileNotExists(string $path)
  Presence of artifacts.

For later

• outputContains(string $expected, callable $fn) / outputNotContains(...)
  Run $fn, capture STDOUT, assert substring.

To see:

• PHPUnit asserts
• webmozarts/assert

[petrdobr]

Hello @roxblnfk! I want to summarize discussion from telegram chat about assert functions.

1) Types
We need to specify accepted types for each function and make assertions more specific, rather than universal. As I understand, the philosophy here should be that we guarantee predictable behavior for limited number of types and we do not let user put into assert methods unexpected data types. For example, we should not let user compare greaterThan for arrays, objects, etc (except DateTime maybe?), and so on.

questions:

1. Type hinting might not cover all accepted cases in some functions. Should there be a check for data types inside Assert methods? Throw some Exception if data type is not expected?
2. Already made assertions same, equals and so on should be reviewed again and acceptable data types should be checked for them as well?

2) Function names
You suggested to think about new way to present Assert methods for comparing functions or even for all of them (with 2 arguments). Constructions like Assert::greaterThan($min, $value), Assert::lessThan($max, $value) should be avoided for their ambiguity.
Suggested new variants were:

• Assert::true($a, $operator, $b), for example Assert::($a, '<', $b), or Assert::($a, 'lessThan', $b). I personally suggest we make it Assert::satisfies($a, $operator, $b)because Assert::true might also be confusing.
• Assert::that($a)->methodName($b). First method that() accepts actual value, and then specific method is applied with expected value as an argument.
• I have crazy idea to re-use data type assertions to chain other asserting methods to them. For example: Assert::string($a) checks if $a is a string, and Assert::string($a)->contains($b) checks if string contains $b in it. I thought how to implement it and have no idea, so it's just a fantasy right now.

questions:

1. What should be chosen? From my perspective, there is no crucial difference (3d option is out of question). Second option might look a bit cleaner to me, but I don't have much experience here.
2. Should this style be used for every method, that is using 2 arguments for assertion, or this approach should be limited by comparison-type assertions? For example, we can do Assert::ObjectHasProperty($object, $propertyName) in these ways too: Assert::satisfies($object 'hasProperty', $propertyName) or Assert::that($object)->hasProperty($propertyName). And any other assert too.

After the scope of changes for assert functions is clarified I can make a new todo list for asserts section with details for you to review

[roxblnfk]

Thank you.
Just repeat here two reasons why I wouldn't want to add Assert::lessThan($max, $value):

• Order of arguments. We are all used to the mathematical notation: A less than B is written as $a < $b, but for consistency, the method has the reverse order Assert::lessThan($b, $a).
• More code, less clarity. Assert::true($a < $b); looks shorter, more readable, and understandable.

To keep moving forward, I'll remind you that the Assert::blank method is still in demand.

Answers:

1. I like the idea of Assert::string($a)->contains($b). Unlike Assert::that(), we immediately get a type check and assertions corresponding to that type. Let's create a prototype with one or few methods and see how it looks.
2. Let's stick to this rule:
   • We first implement complex assertions that cannot be replaced with Assert::true(...) and a simple expression.
   • For assertions tied to a specific type, we will create separate type-oriented classes to group the assertions.
     For example, a class that works only with strings. This class will be returned from the Assert::string($a) construction and provide methods like contains($b). If needed, we can always reuse these classes within the main facade.

[petrdobr]

Thank you for answers!
Then short-term plan for me:

• create Assert::blank() method
• create prototype Assert::string() method returning String class and example of contains() method for strings

[petrdobr]

Hi, @roxblnfk
Question about the desired behavior of the chained asserting functions.

Suggest Assert::string($a) is created and it checks for string data type.
Then Assert::string($a)->contains($b) is created as well, chaining to the previous string assert.

If we do for example this test

Assert::string("string")->contains("str");
Assert::string(666);

First we get successful string assert, then sucessfull contains assert and then failure. In history we get something like this:

✓ Assert string is string
✓ Assert string contains
✗ Failed asserting that value is of type `"string"`. Got `"int"`.

Question: do we need to see the first line ✓ Assert string is string for chained asserts? On the one hand, it might be confusing to see and it might spam the output every time one calls chained asserts. On the other hand it only shows when failure occurs, single assert logs are not shown in successful cases, so it might be a rare occasion.

What do you think how's better to show output?

[roxblnfk]

Good question. Let's keep it separate for now (as it is already done), and later we will think about how to combine several messages of one chain into one. This chain can potentially consist of three or more checks.

[roxblnfk]

I've added interfaces in #50 that should be implemented

[petrdobr]

@roxblnfk hi,

I looked up new update in Assert methods API. Liked the idea, only criticism is method's validateAndCreate() name. Though accurate, it looks a bit bulky. Consider these variants as well please:

AssertInt::validate($value)->greaterThan($min);
AssertInt::verify($value)->greaterThan($min);
AssertInt::check($value)->greaterThan($min);
AssertInt::ensure($value)->greaterThan($min);

//to compare
AssertInt::validateAndCreate($value)->greaterThan($min);

[roxblnfk]

Basically, this is an internal method not covered by interfaces. It's similar to a constructor that registers a type check. It can be renamed to ensure, but the create semantics might be lost.

[petrdobr]

Basically, this is an internal method not covered by interfaces. It's similar to a constructor that registers a type check. It can be renamed to ensure, but the create semantics might be lost.

If it is not intended for use in API then validateAndCreate totally fine in my opinion.
If it is a part of some workaround method from Assert::int() (for example) then it might be a bit more smooth to see AssertInt::ensure($a) than AssertInt::validateAndCreate($a). But not necessarily so.

In any case I intend to continue with asserts if you don't mind. I will try to analyze possible new asserts and implement blank methods step by step.