feat: Add docs test suites for MySQL nested sets behavior, covering cache management, exception handling, extensibility, node operations, and validation.

Author: terabytesoftw

tests/mysql/CacheManagementTest.php

@@ -8,6 +8,27 @@
 use yii2\extensions\nestedsets\tests\base\AbstractCacheManagement;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for cache invalidation in nested sets tree behaviors using MySQL.
+ *
+ * Verifies correct cache management, invalidation, and memoization for nested sets tree structures in MySQL
+ * environments, covering node insertions, updates, deletions, and structural changes for both single and multiple tree
+ * models.
+ *
+ * Inherits integration and unit tests from {@see AbstractCacheManagement} to ensure cache lifecycle correctness,
+ * including depth, left, and right attribute handling, and supports both manual and automatic cache invalidation
+ * scenarios.
+ *
+ * Key features.
+ * - Ensures compatibility and correctness of cache logic on the MySQL platform.
+ * - Full coverage of cache population, invalidation, and memoization for nested sets behaviors.
+ * - MySQL-specific configuration for database connection and credentials.
+ *
+ * @see AbstractCacheManagement for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class CacheManagementTest extends AbstractCacheManagement
 {

tests/mysql/ExceptionHandlingTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractExceptionHandling;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for exception handling in nested sets tree behaviors using MySQL.
+ *
+ * Verifies correct exception throwing and error messages for invalid node operations and edge cases in nested sets tree
+ * structures on MySQL, covering both single and multiple tree models.
+ *
+ * Inherits unit tests from {@see AbstractExceptionHandling} to ensure robustness of the nested sets behavior by
+ * simulating invalid operations such as appending, inserting, deleting, and making root nodes under unsupported
+ * conditions.
+ *
+ * Key features.
+ * - Ensures error handling consistency for unsupported operations on MySQL.
+ * - Full coverage for invalid append, insert, delete, and makeRoot operations.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - Support for both single-tree and multi-tree models.
+ * - Tests for exception messages and types in various edge cases.
+ *
+ * @see AbstractExceptionHandling for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class ExceptionHandlingTest extends AbstractExceptionHandling
 {

tests/mysql/ExtensibilityTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractExtensibility;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for extensibility in nested sets tree behaviors using MySQL.
+ *
+ * Verifies that protected methods in the nested sets behavior remain accessible and customizable for subclassing
+ * scenarios on MySQL, ensuring extensibility for advanced use cases in both single-tree and multi-tree models.
+ *
+ * Inherits unit tests from {@see AbstractExtensibility} to validate the exposure and correct execution of key internal
+ * methods, supporting framework extension and advanced customization in descendant classes.
+ *
+ * Key features.
+ * - Ensures protected methods are accessible for subclass extension.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - 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 AbstractExtensibility for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class ExtensibilityTest extends AbstractExtensibility
 {

tests/mysql/MutationTest.php

@@ -5,10 +5,28 @@
 namespace yii2\extensions\nestedsets\tests\mysql;
 
 use PHPUnit\Framework\Attributes\Group;
+use yii\db\Exception;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 use yii2\extensions\nestedsets\tests\support\model\MultipleTree;
 use yii2\extensions\nestedsets\tests\TestCase;
 
+/**
+ * Test suite for mutation operations in nested sets tree behaviors using MySQL.
+ *
+ * Verifies correct handling of leaf node ordering and left attribute consistency in multiple tree models on MySQL.
+ *
+ * Ensures that the `leaves()` method returns nodes in the expected order after direct manipulation of left and right
+ * attributes, maintaining data integrity and predictable query results.
+ *
+ * Key features.
+ * - Ensures consistent results from the `leaves()` method.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - Uses the multiple tree model for mutation scenarios.
+ * - Validates leaf node detection and ordering after manual updates.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mutation')]
 final class MutationTest extends TestCase
 {
@@ -19,6 +37,9 @@ protected function setUp(): void
         parent::setUp();
     }
 
+    /**
+     * @throws Exception if an unexpected error occurs during execution.
+     */
     public function testLeavesMethodRequiresLeftAttributeOrderingForConsistentResults(): void
     {
         $this->createDatabase();
@@ -51,7 +72,7 @@ public function testLeavesMethodRequiresLeftAttributeOrderingForConsistentResult
 
         $leaves = MultipleTree::find()->leaves()->all();
 
-        /** @phpstan-var array<array{name: string, lft: int}> */
+        /** @phpstan-var array<array{name: string, lft: int}> $expectedLeaves */
         $expectedLeaves = [
             ['name' => 'Leaf B', 'lft' => 3],
             ['name' => 'Leaf A', 'lft' => 5],

tests/mysql/NodeAppendTest.php

@@ -8,6 +8,31 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeAppend;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node append and root promotion in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit and integration tests for appending nodes and promoting nodes to root in nested sets tree
+ * structures on MySQL, ensuring correct tree structure, attribute updates, and validation logic for both single-tree
+ * and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeAppend} to validate node append operations, strict validation scenarios, root
+ * promotion, and XML dataset matching after structural changes, covering edge cases such as validation bypass,
+ * attribute refresh requirements, and cross-tree operations.
+ *
+ * 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 for MySQL.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - Root promotion and attribute refresh verification.
+ * - Validation of strict and non-strict append operations.
+ * - XML dataset matching after structural changes.
+ *
+ * @see AbstractNodeAppend for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class NodeAppendTest extends AbstractNodeAppend
 {

tests/mysql/NodeDeleteTest.php

@@ -8,6 +8,30 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeDelete;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node deletion in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit tests for node and subtree deletion operations in nested sets tree structures on MySQL,
+ * ensuring correct state transitions, affected row counts, and data integrity after deletions for both single-tree and
+ * multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeDelete} to validate node deletion, subtree removals, abort scenarios,
+ * transactional behavior, and update operations on node attributes, covering edge cases and XML dataset consistency
+ * after deletions.
+ *
+ * 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.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - 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 AbstractNodeDelete for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class NodeDeleteTest extends AbstractNodeDelete
 {

tests/mysql/NodeInsertTest.php

@@ -8,6 +8,30 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeInsert;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node insertion in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit tests for node insertion operations in nested sets tree structures on MySQL, ensuring
+ * correct behavior for inserting nodes before and after targets, with and without validation, and across both
+ * single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodeInsert} to validate insertion logic, strict validation scenarios, cross-tree
+ * insertions, and XML dataset matching after structural changes, covering edge cases such as validation bypass,
+ * attribute refresh requirements, and multi-tree operations.
+ *
+ * Key features.
+ * - Covers both {@see Tree} and {@see MultipleTree} model scenarios.
+ * - Edge case handling for strict validation and cross-tree insertions.
+ * - Ensures correct left, right, depth, and tree attribute updates for MySQL.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - Validation of strict and non-strict insert operations.
+ * - XML dataset matching after structural changes.
+ *
+ * @see AbstractNodeInsert for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class NodeInsertTest extends AbstractNodeInsert
 {

tests/mysql/NodePrependTest.php

@@ -8,6 +8,29 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodePrepend;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node prepend operations in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit and integration tests for prepending nodes in nested sets tree structures on MySQL,
+ * ensuring correct tree structure, attribute updates, and validation logic for both single-tree and multi-tree models.
+ *
+ * Inherits tests from {@see AbstractNodePrepend} to validate node prepend operations, strict validation scenarios, and
+ * XML dataset matching after structural changes, covering edge cases such as validation bypass, attribute refresh
+ * requirements, and cross-tree operations.
+ *
+ * Key features.
+ * - Covers both {@see Tree} and {@see MultipleTree} model scenarios.
+ * - Ensures correct left, right, depth, and tree attribute updates after prepend operations for MySQL.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - 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 AbstractNodePrepend for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class NodePrependTest extends AbstractNodePrepend
 {

tests/mysql/NodeStateTest.php

@@ -8,6 +8,28 @@
 use yii2\extensions\nestedsets\tests\base\AbstractNodeState;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for node state and relationship in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit tests for verifying node state, parent-child relationships, and root/leaf detection in
+ * both single-tree and multi-tree nested sets models on MySQL.
+ *
+ * Inherits tests from {@see AbstractNodeState} to ensure 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.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - Tests for `isChildOf()` under different ancestor and boundary scenarios.
+ * - Validation of `isRoot()` and `isLeaf()` logic for root, leaf, and intermediate nodes.
+ *
+ * @see AbstractNodeState for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class NodeStateTest extends AbstractNodeState
 {

tests/mysql/QueryBehaviorTest.php

@@ -8,6 +8,29 @@
 use yii2\extensions\nestedsets\tests\base\AbstractQueryBehavior;
 use yii2\extensions\nestedsets\tests\support\DatabaseConnection;
 
+/**
+ * Test suite for query behavior in nested sets tree behaviors using MySQL.
+ *
+ * Provides comprehensive unit tests for query methods related to leaf and root node retrieval, ordering, and behavior
+ * attachment in both single-tree and multi-tree nested sets models on MySQL, ensuring correctness of query methods
+ * such as `leaves()` and `roots()`, including ordering guarantees, SQL generation, and error handling when the behavior
+ * is detached or not attached to the owner.
+ *
+ * Inherits tests from {@see AbstractQueryBehavior} to validate deterministic ordering, correct node retrieval, SQL
+ * structure, and exception handling for query behaviors.
+ *
+ * Key features.
+ * - Ensures deterministic ordering of results by left and tree attributes.
+ * - MySQL-specific configuration for database connection and credentials.
+ * - 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 AbstractQueryBehavior for test logic and scenarios.
+ *
+ * @copyright Copyright (C) 2023 Terabytesoftw.
+ * @license https://opensource.org/license/bsd-3-clause BSD 3-Clause License.
+ */
 #[Group('mysql')]
 final class QueryBehaviorTest extends AbstractQueryBehavior
 {