diff --git a/tests/base/AbstractCacheManagement.php b/tests/base/AbstractCacheManagement.php index 7bb7518..a77e853 100644 --- a/tests/base/AbstractCacheManagement.php +++ b/tests/base/AbstractCacheManagement.php @@ -12,6 +12,34 @@ use yii2\extensions\nestedsets\tests\support\stub\ExtendableNestedSetsBehavior; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for cache invalidation tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of integration and unit tests for cache management in nested sets tree structures, + * ensuring correct cache population, invalidation, and memoization across various node operations and scenarios. + * + * This class validates the cache lifecycle for the nested sets behavior by simulating node insertions, updates, + * deletions, and structural changes, covering both single and multiple tree models. + * + * The tests ensure that cache values for depth, left, and right attributes are correctly populated, invalidated, and + * memoized, and that cache invalidation is triggered by all relevant operations, including manual and automatic cases. + * + * Key features. + * - Coverage for tree attribute handling and owner assignment. + * - Integration tests for cache invalidation after node insert, update, append, delete, and makeRoot operations. + * - Memoization tests for depth, left, and right value accessors. + * - Support for both single-tree and multi-tree models. + * - Tests for manual and automatic cache invalidation. + * - Use of mock objects to verify memoization and cache state. + * - Verification of cache state before and after invalidation events. + * + * @see MultipleTree for multi-tree model. + * @see NestedSetsBehavior for behavior implementation. + * @see Tree for single-tree model. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractCacheManagement extends TestCase { public function testAfterInsertCacheInvalidationIntegration(): void diff --git a/tests/base/AbstractExceptionHandling.php b/tests/base/AbstractExceptionHandling.php index 5a184f2..5a451b2 100644 --- a/tests/base/AbstractExceptionHandling.php +++ b/tests/base/AbstractExceptionHandling.php @@ -9,10 +9,36 @@ use yii\base\NotSupportedException; use yii\db\{Exception, StaleObjectException}; use yii2\extensions\nestedsets\NestedSetsBehavior; -use yii2\extensions\nestedsets\tests\support\model\MultipleTree; -use yii2\extensions\nestedsets\tests\support\model\Tree; +use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for exception handling tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of unit tests for exception scenarios in nested sets tree structures, ensuring correct + * exception throwing and error messages for invalid node operations and edge cases. + * + * This class validates the robustness of the nested sets behavior by simulating invalid operations such as appending, + * inserting, deleting, and making root nodes under unsupported conditions, covering both single and multiple tree + * models. + * + * The tests ensure that exceptions are thrown with the expected messages for cases like new records, root nodes, child + * nodes, same node operations, and missing primary keys, as well as logic errors when the behavior is not attached. + * + * Key features. + * - Coverage for invalid append, insert, delete, and makeRoot operations. + * - Ensures error handling consistency for unsupported operations. + * - Support for both single-tree and multi-tree models. + * - Tests for exception messages and types in various edge cases. + * - Validation of logic exceptions when the behavior is detached or not attached to the owner. + * + * @see MultipleTree for multi-tree model. + * @see NestedSetsBehavior for behavior implementation. + * @see Tree for single-tree model. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractExceptionHandling extends TestCase { public function testThrowExceptionWhenAppendToNewNodeTargetIsNewRecord(): void @@ -84,8 +110,9 @@ public function testThrowExceptionWhenAppendToTargetIsSame(): void } /** - * @throws StaleObjectException - * @throws Throwable + * @throws StaleObjectException if optimistic, locking is enabled and the data to be deleted has been modified by + * another process. + * @throws Throwable if an unexpected error occurs during execution. */ public function testThrowExceptionWhenDeleteNodeIsNewRecord(): void { @@ -442,8 +469,9 @@ public function testThrowLogicExceptionWhenBehaviorIsNotAttachedToOwner(): void } /** - * @throws StaleObjectException - * @throws Throwable + * @throws StaleObjectException if optimistic, locking is enabled and the data to be deleted has been modified by + * another process. + * @throws Throwable if an unexpected error occurs during execution. */ public function testThrowNotSupportedExceptionWhenDeleteIsCalledOnRootNode(): void { @@ -465,7 +493,7 @@ public function testThrowNotSupportedExceptionWhenDeleteIsCalledOnRootNode(): vo } /** - * @throws Throwable + * @throws Throwable if an unexpected error occurs during execution. */ public function testThrowNotSupportedExceptionWhenInsertIsCalledOnTree(): void { diff --git a/tests/base/AbstractExtensibility.php b/tests/base/AbstractExtensibility.php index bd201e2..8ad4e5a 100644 --- a/tests/base/AbstractExtensibility.php +++ b/tests/base/AbstractExtensibility.php @@ -8,6 +8,32 @@ use yii2\extensions\nestedsets\tests\support\stub\ExtendableNestedSetsBehavior; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for extensibility tests in nested sets tree behaviors. + * + * Provides a suite of unit tests to verify the extensibility and subclassing capabilities of the nested sets behavior, + * ensuring protected methods remain accessible for customization and extension in descendant classes. + * + * This class validates that key internal methods of the nested sets behavior—such as node insertion, root insertion, + * node movement, and attribute shifting—can be invoked and overridden by subclasses, supporting advanced use cases + * and framework extensibility. + * + * The tests cover scenarios for exposing protected methods, confirming their correct execution and the ability to + * customize node state during tree operations in both single-tree and multi-tree models. + * + * Key features. + * - Ensures protected methods are accessible for subclass extension. + * - Supports both single-tree and multi-tree model scenarios. + * - Tests before-insert and move operations for extensibility. + * - Validates extensibility for root and non-root node operations. + * - Verifies correct attribute assignment by protected methods. + * + * @see ExtendableMultipleTree for extensible multi-tree model. + * @see ExtendableNestedSetsBehavior for behavior subclass exposing protected methods. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractExtensibility extends TestCase { public function testProtectedBeforeInsertNodeRemainsAccessibleToSubclasses(): void diff --git a/tests/base/AbstractNodeAppend.php b/tests/base/AbstractNodeAppend.php index 9e9501b..001efd9 100644 --- a/tests/base/AbstractNodeAppend.php +++ b/tests/base/AbstractNodeAppend.php @@ -8,6 +8,35 @@ use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree, TreeWithStrictValidation}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for node append and root promotion tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of unit and integration tests for appending nodes and promoting nodes to root in + * nested sets tree structures, ensuring correct tree structure, attribute updates, and validation logic for both + * single-tree and multi-tree models. + * + * This class validates the correctness of node append operations, strict validation scenarios, root promotion, and XML + * dataset matching after structural changes. + * + * It covers edge cases such as validation bypass, attribute refresh requirements, and cross-tree operations, ensuring + * robust behavior for all supported node manipulations. + * + * Key features. + * - Covers both {@see Tree} and {@see MultipleTree} model scenarios. + * - Cross-tree append operations for multi-tree models. + * - Ensures correct left, right, depth, and tree attribute updates. + * - Root promotion and attribute refresh verification. + * - Tests for appending child nodes to root and other nodes. + * - Validation of strict and non-strict append operations. + * - XML dataset matching after structural changes. + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * @see TreeWithStrictValidation for strict validation scenarios. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractNodeAppend extends TestCase { public function testAppendChildNodeToRootCreatesValidTreeStructure(): void diff --git a/tests/base/AbstractNodeDelete.php b/tests/base/AbstractNodeDelete.php index 4a6659d..b7420f9 100644 --- a/tests/base/AbstractNodeDelete.php +++ b/tests/base/AbstractNodeDelete.php @@ -4,11 +4,37 @@ namespace yii2\extensions\nestedsets\tests\base; +use PHPUnit\Framework\MockObject\Exception; use Throwable; use yii\db\{ActiveRecord, StaleObjectException}; use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for node deletion tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of unit tests for node deletion operations in nested sets tree structures, ensuring + * correct state transitions, affected row counts, and data integrity after node and subtree deletions. + * + * This class validates the behavior of the nested sets implementation by simulating node deletions, subtree removals, + * and update operations, covering both single and multiple tree models. + * + * The tests also cover abort scenarios for deletions, transactional behavior, and update operations on node attributes. + * + * Key features. + * - Covers update operations and affected row count for node attribute changes. + * - Ensures correct affected row counts for node and subtree deletions in both {@see Tree} and {@see MultipleTree} + * models. + * - Tests aborting deletions via `beforeDelete()` and transactional behavior. + * - Validates XML dataset consistency after deletions. + * - Verifies node state transitions after `deleteWithChildren()` (new record status, old attributes). + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractNodeDelete extends TestCase { public function testNodeStateAfterDeleteWithChildren(): void @@ -76,6 +102,9 @@ public function testReturnAffectedRowsAndMatchXmlAfterDeleteWithChildrenForTreeA ); } + /** + * @throws Exception if an unexpected error occurs during execution. + */ public function testReturnFalseWhenDeleteWithChildrenIsAbortedByBeforeDelete(): void { $this->createDatabase(); @@ -112,8 +141,9 @@ public function testReturnFalseWhenDeleteWithChildrenIsAbortedByBeforeDelete(): } /** - * @throws StaleObjectException - * @throws Throwable + * @throws StaleObjectException if optimistic, locking is enabled and the data to be deleted has been modified by + * another process. + * @throws Throwable if an unexpected error occurs during execution. */ public function testReturnOneWhenDeleteNodeForTreeAndMultipleTree(): void { @@ -145,8 +175,9 @@ public function testReturnOneWhenDeleteNodeForTreeAndMultipleTree(): void } /** - * @throws Throwable - * @throws StaleObjectException + * @throws StaleObjectException if optimistic, locking is enabled and the data to be deleted has been modified by + * another process. + * @throws Throwable if an unexpected error occurs during execution. */ public function testReturnOneWhenUpdateNodeName(): void { diff --git a/tests/base/AbstractNodeInsert.php b/tests/base/AbstractNodeInsert.php index 354f11c..f6a8bfc 100644 --- a/tests/base/AbstractNodeInsert.php +++ b/tests/base/AbstractNodeInsert.php @@ -7,6 +7,33 @@ use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree, TreeWithStrictValidation}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for node insertion tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of unit tests for node insertion operations in nested sets tree structures, ensuring + * correct behavior for inserting nodes before and after targets, with and without validation, and across both single + * and multiple tree models. + * + * This class validates the insertion logic by simulating scenarios such as inserting new and existing nodes, handling + * validation rules, and verifying the resulting tree structure against expected XML datasets. + * + * It covers edge cases for strict validation, cross-tree insertions, and ensures that the tree state matches the + * expected outcome after each operation. + * + * Key features. + * - Coverage for `insertAfter()` and `insertBefore()` operations with and without validation. + * - Edge case handling for inserting new nodes, moving existing nodes, and cross-tree insertions. + * - Support for both single-tree and multi-tree models. + * - Tests for strict validation and bypassing validation logic. + * - XML dataset comparison to verify tree structure after insertions. + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * @see TreeWithStrictValidation for strict validation scenarios. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractNodeInsert extends TestCase { public function testInsertAfterWithRunValidationParameterUsingStrictValidation(): void diff --git a/tests/base/AbstractNodePrepend.php b/tests/base/AbstractNodePrepend.php index bb1271e..3f7a773 100644 --- a/tests/base/AbstractNodePrepend.php +++ b/tests/base/AbstractNodePrepend.php @@ -7,6 +7,32 @@ use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree, TreeWithStrictValidation}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for node prepend tests in nested sets tree behaviors. + * + * Provides a comprehensive suite of unit and integration tests for prepending nodes in nested sets tree structures, + * ensuring correct tree structure, attribute updates, and validation logic for both single-tree and multi-tree models. + * + * This class validates the correctness of node prepend operations, strict validation scenarios, and XML dataset + * matching after structural changes. + * + * It covers edge cases such as validation bypass and attribute refresh requirements, ensuring robust behavior for all + * supported node manipulations. + * + * Key features. + * - Covers both {@see Tree} and {@see MultipleTree} model scenarios. + * - Ensures correct left, right, depth, and tree attribute updates after prepend operations. + * - Tests for prepending new and existing nodes, including cross-tree operations. + * - Validation of strict and non-strict prepend operations. + * - XML dataset matching after structural changes. + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * @see TreeWithStrictValidation for strict validation scenarios. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractNodePrepend extends TestCase { public function testPrependToWithRunValidationParameterUsingStrictValidation(): void diff --git a/tests/base/AbstractNodeState.php b/tests/base/AbstractNodeState.php index c80b94a..4dfd70e 100644 --- a/tests/base/AbstractNodeState.php +++ b/tests/base/AbstractNodeState.php @@ -4,10 +4,30 @@ namespace yii2\extensions\nestedsets\tests\base; -use yii2\extensions\nestedsets\tests\support\model\MultipleTree; -use yii2\extensions\nestedsets\tests\support\model\Tree; +use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for node state and relationship tests in nested sets tree behaviors. + * + * Provides a suite of unit tests for verifying node state, parent-child relationships, and root/leaf detection in both + * single-tree and multi-tree nested sets models. + * + * This class ensures the correctness of methods that determine node ancestry, root status, and leaf status by testing + * various edge cases and boundary conditions, such as equal left/right values and ancestor chains. + * + * Key features. + * - Coverage for both {@see Tree} and {@see MultipleTree} model implementations. + * - Ensures correct behavior for left/right value manipulations and ancestor checks. + * - Tests for `isChildOf()` under different ancestor and boundary scenarios. + * - Validation of `isRoot()` and `isLeaf()` logic for root, leaf, and intermediate nodes. + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractNodeState extends TestCase { public function testIsChildOfReturnsFalseWhenLeftValuesAreEqual(): void diff --git a/tests/base/AbstractQueryBehavior.php b/tests/base/AbstractQueryBehavior.php index 2dfbbdd..e293324 100644 --- a/tests/base/AbstractQueryBehavior.php +++ b/tests/base/AbstractQueryBehavior.php @@ -5,13 +5,39 @@ namespace yii2\extensions\nestedsets\tests\base; use LogicException; +use yii\db\Exception; use yii\helpers\ArrayHelper; use yii2\extensions\nestedsets\NestedSetsQueryBehavior; use yii2\extensions\nestedsets\tests\support\model\{MultipleTree, Tree, TreeQuery}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for query behavior tests in nested sets tree behaviors. + * + * Provides a suite of unit tests for verifying query methods related to leaf and root node retrieval, ordering, and + * behavior attachment in both single-tree and multi-tree nested sets models. + * + * This class ensures the correctness of query methods such as `leaves()` and `roots()`, including their ordering + * guarantees, SQL generation, and error handling when the behavior is detached or not attached to the owner. + * + * Key features. + * - Ensures deterministic ordering of results by left attribute and tree attribute. + * - Tests for correct leaf and root node retrieval in {@see Tree} and {@see MultipleTree} models. + * - Validates SQL query structure for ordering requirements. + * - Verifies exception handling when the behavior is detached or not attached to the query owner. + * + * @see MultipleTree for multi-tree model. + * @see NestedSetsQueryBehavior for query behavior implementation. + * @see Tree for single-tree model. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractQueryBehavior extends TestCase { + /** + * @throws Exception if an unexpected error occurs during execution. + */ public function testLeavesMethodRequiresLeftAttributeOrderingForConsistentResults(): void { $this->createDatabase(); @@ -44,7 +70,7 @@ public function testLeavesMethodRequiresLeftAttributeOrderingForConsistentResult $leaves = MultipleTree::find()->leaves()->all(); - /** @phpstan-var array */ + /** @phpstan-var array $expectedLeaves */ $expectedLeaves = [ ['name' => 'Leaf B', 'lft' => 3], ['name' => 'Leaf A', 'lft' => 5], @@ -160,6 +186,9 @@ public function testRootsMethodRequiresLeftAttributeOrderingWhenTreeAttributeIsD } } + /** + * @throws Exception if an unexpected error occurs during execution. + */ public function testRootsMethodRequiresOrderByForCorrectTreeTraversal(): void { $this->createDatabase(); diff --git a/tests/base/AbstractTreeTraversal.php b/tests/base/AbstractTreeTraversal.php index 8f19131..b6c31dc 100644 --- a/tests/base/AbstractTreeTraversal.php +++ b/tests/base/AbstractTreeTraversal.php @@ -9,9 +9,31 @@ use yii2\extensions\nestedsets\tests\TestCase; /** + * Base class for tree traversal and relationship tests in nested sets tree behaviors. + * + * Provides a suite of unit tests for verifying traversal methods, node ordering, and parent/child/leaf relationships in + * both single-tree and multi-tree nested sets models. + * + * This class ensures the correctness and determinism of methods that retrieve children, leaves, parents, next, and + * previous nodes, including order-by requirements and depth constraints, by testing various tree structures and update + * scenarios. + * + * Key features. + * - Comparison of actual results with expected fixtures for all traversal methods. + * - Coverage for both {@see Tree} and {@see MultipleTree} model implementations. + * - Ensures correct node ordering and deterministic traversal for children, leaves, and parents. + * - Tests for order-by enforcement in traversal queries. + * - Validation of depth constraints and structure updates. + * + * @see MultipleTree for multi-tree model. + * @see Tree for single-tree model. + * * @phpstan-type NodeChildren array}> * @phpstan-type TreeStructure array> * @phpstan-type UpdateData array + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. */ abstract class AbstractTreeTraversal extends TestCase { diff --git a/tests/base/AbstractValidationAndStructure.php b/tests/base/AbstractValidationAndStructure.php index fabdba2..0987698 100644 --- a/tests/base/AbstractValidationAndStructure.php +++ b/tests/base/AbstractValidationAndStructure.php @@ -8,6 +8,32 @@ use yii2\extensions\nestedsets\tests\support\model\{Tree, TreeWithStrictValidation}; use yii2\extensions\nestedsets\tests\TestCase; +/** + * Base class for validation and structural integrity tests in nested sets tree behaviors. + * + * Provides a focused suite of unit tests for validating node creation, root assignment, and structural attribute + * correctness in nested sets tree models, including strict validation scenarios and direct manipulation of node + * attributes during insertion. + * + * This class ensures that node validation logic, left/right attribute shifting, and depth assignment are correctly + * handled when creating root nodes, appending children, and invoking internal behavior methods. + * + * It covers both validation-enabled and validation-bypassed operations, as well as direct calls to behavior hooks for + * attribute initialization. + * + * Key features. + * - Ensures correct attribute assignment when appending children to root nodes. + * - Tests strict validation logic for root node creation with and without validation enforcement. + * - Validates direct invocation of behavior hooks for node attribute initialization. + * - Verifies left, right, and depth attribute values after root and child node operations. + * + * @see NestedSetsBehavior for behavior implementation and hooks. + * @see Tree for standard nested sets model. + * @see TreeWithStrictValidation for strict validation scenarios. + * + * @copyright Copyright (C) 2023 Terabytesoftw. + * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License. + */ abstract class AbstractValidationAndStructure extends TestCase { public function testMakeRootWithRunValidationParameterUsingStrictValidation(): void @@ -133,7 +159,7 @@ public function setNodeToNull(): void public function getNodeDepth(): int|null { - return $this->node !== null ? $this->node->getAttribute($this->depthAttribute) : null; + return $this->node?->getAttribute($this->depthAttribute); } };