@arcadialdev/arcality 2.2.0

package/tests/_helpers/qa-tools.ts

@@ -0,0 +1,333 @@
+/**
+ * QA Advanced Tools - Fase 1 (Críticas)
+ * 
+ * Este archivo contiene las definiciones de tools avanzadas para el agente QA.
+ * Estas tools permiten validaciones, extracción de datos, y detección de errores.
+ * 
+ * @created 2026-02-13
+ */
+
+// ============================================================================
+// TOOL 1: validate_element_state
+// ============================================================================
+export const validateElementStateTool = {
+    name: "validate_element_state",
+    description: "QA Skill: Validate that an element meets expected conditions (exists, visible, enabled, disabled, contains text, has value). Use this for assertions during test execution WITHOUT executing actions. This is the KEY tool for verifying application state.",
+    input_schema: {
+        type: "object",
+        properties: {
+            idx: {
+                type: "number",
+                description: "The IDX of the element to validate"
+            },
+            validations: {
+                type: "array",
+                description: "List of validations to perform on this element",
+                items: {
+                    type: "object",
+                    properties: {
+                        type: {
+                            enum: ["exists", "visible", "enabled", "disabled", "contains_text", "has_value", "is_empty", "has_class"],
+                            description: "Type of validation to perform"
+                        },
+                        expected_value: {
+                            type: "string",
+                            description: "Expected value (required for: contains_text, has_value, has_class)"
+                        }
+                    },
+                    required: ["type"]
+                }
+            }
+        },
+        required: ["idx", "validations"]
+    }
+};
+
+// ============================================================================
+// TOOL 2: extract_table_data
+// ============================================================================
+export const extractTableDataTool = {
+    name: "extract_table_data",
+    description: "QA Skill: Extract structured data from tables or lists on the page. Use this to validate datasets, counts, or specific values. Returns an array of objects representing rows with their data.",
+    input_schema: {
+        type: "object",
+        properties: {
+            table_identifier: {
+                type: "string",
+                description: "Text content near the table, aria-label, or distinctive text that identifies the table (e.g., 'Timesheet - Hoy', 'Listado de pendientes')"
+            },
+            max_rows: {
+                type: "number",
+                description: "Maximum number of rows to extract (default: 50)",
+                default: 50
+            },
+            filter_column: {
+                type: "string",
+                description: "Optional: Column name to filter by"
+            },
+            filter_value: {
+                type: "string",
+                description: "Optional: Value to match in the filter column"
+            }
+        },
+        required: ["table_identifier"]
+    }
+};
+
+// ============================================================================
+// TOOL 3: capture_console_errors
+// ============================================================================
+export const captureConsoleErrorsTool = {
+    name: "capture_console_errors",
+    description: "QA Skill: Capture JavaScript console errors, warnings, and network failures that occurred during the test. Use this to detect client-side bugs that are not visible in the UI. This is CRITICAL for detecting hidden issues.",
+    input_schema: {
+        type: "object",
+        properties: {
+            severity_filter: {
+                enum: ["all", "error", "warning"],
+                description: "Filter by severity level (default: error)",
+                default: "error"
+            },
+            include_network_errors: {
+                type: "boolean",
+                description: "Include failed network requests (HTTP errors)",
+                default: true
+            }
+        }
+    }
+};
+
+// ============================================================================
+// TOOL 4: assert_url_pattern
+// ============================================================================
+export const assertUrlPatternTool = {
+    name: "assert_url_pattern",
+    description: "QA Skill: Validate that the current URL matches (or doesn't match) an expected pattern. Use this to ensure navigation worked correctly or to verify you're on the expected page.",
+    input_schema: {
+        type: "object",
+        properties: {
+            pattern: {
+                type: "string",
+                description: "URL pattern to match (can be a substring like '/welcome' or a full URL)"
+            },
+            should_match: {
+                type: "boolean",
+                description: "True if URL should contain the pattern, false if it should NOT",
+                default: true
+            }
+        },
+        required: ["pattern"]
+    }
+};
+
+// ============================================================================
+// TOOL 5: measure_page_performance
+// ============================================================================
+export const measurePagePerformanceTool = {
+    name: "measure_page_performance",
+    description: "QA Skill: Measure page load time, network requests, and performance metrics (FCP, DOM loaded, total load). Use this to validate performance requirements or SLAs. Returns measured values and PASS/FAIL against optional thresholds.",
+    input_schema: {
+        type: "object",
+        properties: {
+            metrics_to_capture: {
+                type: "array",
+                items: {
+                    enum: ["load_time", "dom_content_loaded", "first_contentful_paint", "network_requests", "resource_size"]
+                },
+                description: "Metrics to measure (default: all available)"
+            },
+            thresholds: {
+                type: "object",
+                description: "Optional thresholds for PASS/FAIL evaluation (e.g., {load_time_ms: 3000, dom_content_loaded_ms: 2000})",
+                properties: {
+                    load_time_ms: { type: "number", description: "Maximum acceptable page load time in ms" },
+                    dom_content_loaded_ms: { type: "number", description: "Maximum acceptable DOM content loaded time in ms" },
+                    first_contentful_paint_ms: { type: "number", description: "Maximum acceptable FCP in ms" },
+                    max_network_requests: { type: "number", description: "Maximum number of network requests allowed" },
+                    max_resource_size_kb: { type: "number", description: "Maximum total resource size in KB" }
+                }
+            }
+        }
+    }
+};
+
+// ============================================================================
+// TOOL 6: save_navigation_checkpoint
+// ============================================================================
+export const saveNavigationCheckpointTool = {
+    name: "save_navigation_checkpoint",
+    description: "QA Skill: Save the current page state (URL, cookies, localStorage, sessionStorage) as a named checkpoint. Use this before testing multiple paths from the same starting point, so you can restore later without repeating setup steps.",
+    input_schema: {
+        type: "object",
+        properties: {
+            checkpoint_name: {
+                type: "string",
+                description: "Unique name for this checkpoint (e.g., 'form_filled', 'logged_in', 'before_submit')"
+            },
+            include_storage: {
+                type: "boolean",
+                description: "Save localStorage and sessionStorage (default: true)",
+                default: true
+            }
+        },
+        required: ["checkpoint_name"]
+    }
+};
+
+// ============================================================================
+// TOOL 7: restore_navigation_checkpoint
+// ============================================================================
+export const restoreNavigationCheckpointTool = {
+    name: "restore_navigation_checkpoint",
+    description: "QA Skill: Restore a previously saved checkpoint to return to that page state. This navigates back to the saved URL and restores cookies/storage. Use this to test alternative paths from the same starting point without re-running the entire flow.",
+    input_schema: {
+        type: "object",
+        properties: {
+            checkpoint_name: {
+                type: "string",
+                description: "Name of the checkpoint to restore (must have been saved previously)"
+            }
+        },
+        required: ["checkpoint_name"]
+    }
+};
+
+// ============================================================================
+// TOOL 8: create_test_evidence
+// ============================================================================
+export const createTestEvidenceTool = {
+    name: "create_test_evidence",
+    description: "QA Skill: Create visual test evidence (screenshots or annotated screenshots) and save them to disk. Use 'screenshot' for a plain capture, 'annotated_screenshot' to highlight specific elements with colored borders and labels, or 'full_page_screenshot' for a full-page capture. Evidence files are saved for bug reports and test documentation.",
+    input_schema: {
+        type: "object",
+        properties: {
+            evidence_type: {
+                enum: ["screenshot", "annotated_screenshot", "full_page_screenshot"],
+                description: "Type of evidence to create"
+            },
+            annotations: {
+                type: "array",
+                description: "Elements to highlight with labels (only for 'annotated_screenshot')",
+                items: {
+                    type: "object",
+                    properties: {
+                        idx: { type: "number", description: "IDX of the element to highlight" },
+                        label: { type: "string", description: "Annotation text to display near the element" },
+                        color: { type: "string", description: "Highlight color (default: red)", default: "red" }
+                    },
+                    required: ["idx", "label"]
+                }
+            },
+            save_as: {
+                type: "string",
+                description: "Filename for the evidence (without extension, .png will be added). Example: 'bug_save_button_disabled'"
+            },
+            description: {
+                type: "string",
+                description: "Description of what this evidence proves or highlights"
+            },
+            finish_run: {
+                type: "boolean",
+                description: "If true, immediately ends the mission after saving evidence (saves tokens). Use this for final success evidence."
+            }
+        },
+        required: ["evidence_type", "save_as"]
+    }
+};
+
+// ============================================================================
+// TOOL 9: send_keyboard_event
+// ============================================================================
+export const sendKeyboardEventTool = {
+    name: "send_keyboard_event",
+    description: "QA Skill: Send a keyboard event to the page or a specific element. Use this for: pressing Escape to close modals/popups, pressing Tab to navigate between form fields, pressing Enter to submit or confirm, pressing Arrow keys to navigate within date/time pickers, dropdowns, sliders, or any custom component that responds to keyboard input. This is CRITICAL for native browser controls (time pickers, date pickers, color pickers) that do not respond well to 'fill'.",
+    input_schema: {
+        type: "object",
+        properties: {
+            key: {
+                type: "string",
+                description: "The key to press. Supported values: 'Escape', 'Enter', 'Tab', 'Backspace', 'Delete', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown', 'Space', or any single character like 'a', '1', etc. For key combinations use '+' separator: 'Control+a', 'Shift+Tab'."
+            },
+            idx: {
+                type: "number",
+                description: "Optional: IDX of the element to focus before sending the key. If not provided, the key is sent to whatever element currently has focus."
+            },
+            repeat: {
+                type: "number",
+                description: "Number of times to press the key (default: 1). Useful for ArrowUp/ArrowDown in time pickers.",
+                default: 1
+            }
+        },
+        required: ["key"]
+    }
+};
+
+// ============================================================================
+// TOOL 10: interact_native_control
+// ============================================================================
+export const interactNativeControlTool = {
+    name: "interact_native_control",
+    description: "QA Skill: Interact with native HTML controls that standard click/fill may not handle correctly. This includes: <input type='time'>, <input type='date'>, <input type='datetime-local'>, <input type='color'>, <input type='range'>, <select> with optgroup, and contenteditable elements. This tool uses Playwright's specialized methods (selectOption, fill with format coercion, press sequences) to reliably set values. ALWAYS prefer this tool over manual fill for time/date inputs.",
+    input_schema: {
+        type: "object",
+        properties: {
+            idx: {
+                type: "number",
+                description: "The IDX of the native control element"
+            },
+            control_type: {
+                enum: ["time", "date", "datetime", "color", "range", "select", "contenteditable"],
+                description: "The type of native control"
+            },
+            value: {
+                type: "string",
+                description: "The value to set. Formats: time='HH:mm' or 'HH:mm:ss', date='YYYY-MM-DD', datetime='YYYY-MM-DDTHH:mm', color='#rrggbb', range='number', select='option text or value', contenteditable='text to type'."
+            }
+        },
+        required: ["idx", "control_type", "value"]
+    }
+};
+
+// ============================================================================
+// TOOL 11: scroll_page
+// ============================================================================
+export const scrollPageTool = {
+    name: "scroll_page",
+    description: "QA Skill: Scroll the page or a specific container to reveal elements that are outside the current viewport. Use this when: you cannot find an expected element in CURRENT COMPONENTS (it might be below the fold), a form has many fields and you need to see more, or you need to scroll to a specific element. After scrolling, the page state will be refreshed in the next turn.",
+    input_schema: {
+        type: "object",
+        properties: {
+            direction: {
+                enum: ["up", "down", "left", "right", "top", "bottom"],
+                description: "Direction to scroll. 'top' and 'bottom' scroll all the way to the start/end."
+            },
+            amount: {
+                type: "number",
+                description: "Pixels to scroll (default: 500). Ignored for 'top' and 'bottom' directions.",
+                default: 500
+            },
+            idx: {
+                type: "number",
+                description: "Optional: IDX of a scrollable container. If omitted, scrolls the main page."
+            }
+        },
+        required: ["direction"]
+    }
+};
+
+// ============================================================================
+// EXPORT ALL TOOLS
+// ============================================================================
+export const qaAdvancedTools = [
+    validateElementStateTool,
+    extractTableDataTool,
+    captureConsoleErrorsTool,
+    assertUrlPatternTool,
+    measurePagePerformanceTool,
+    saveNavigationCheckpointTool,
+    restoreNavigationCheckpointTool,
+    createTestEvidenceTool,
+    sendKeyboardEventTool,
+    interactNativeControlTool,
+    scrollPageTool
+];