docs: Enhance test classes with comprehensive documentation for nested sets behavior. (#70)

Author: terabytesoftw

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

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
     {

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

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

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
     {

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

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

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