Arcality is an enterprise-grade autonomous testing agent designed by Arcadial. It replaces brittle, hard-coded UI automation with an intelligent, self-healing agent that understands natural language. Powered by our proprietary AI Cognitive Core and Headless Execution Engine, Arcality navigates web portals, fills forms dynamically, and verifies business logic without requiring you to write a single line of test code.

✨ Core Capabilities

• 🧠 Cognitive Execution Pipeline: Arcality doesn't just click coordinates. It parses the DOM tree into an accessibility-focused abstraction, allowing it to "see" your application identically to a human user.
• 🛡️ Self-Healing & Forensic Debugging: When elements shift or modals block the screen, Arcality doesn't instantly crash. It utilizes injected E2E Expert Protocols to debug the DOM, wait for networks, and gracefully recover.
• ♻️ YAML Persistence: Once the Agent figures out how to successfully complete a prompt, the deterministic solution is saved locally as an optimized .yaml mission for lightning-fast regression testing in CI/CD.
• 📊 Agentic Diagnostics HTML Report: Forget raw stack traces. Arcality generates beautiful, dark-mode index.html reports focusing entirely on Agent Cognitive Process and visual attachments.
• 🧰 Project-Centric Architecture: Runs seamlessly locally with arcality.config.json. No messy global .env files required.

🚀 Getting Started

1. Install in your project

npm install @arcadialdev/arcality

After install, Arcality automatically adds the following scripts to your package.json:

"arcality":       "arcality run",
"arcality:init":  "arcality init",
"arcality:run":   "arcality run"

2. Initialize your project

Run the setup wizard at the root of your project. Arcality will auto-detect your framework and scaffold the arcality.config.json.

npm run arcality:init

3. Run an autonomous mission

# Interactive menu
npm run arcality

# Direct mission
npm run arcality:run

🛠️ Internal Architecture

Arcality operates on a highly decoupled modular system designed for maximum resilience:

1. The CLI Wrapper: A Node.js CLI that orchestrates Playwright subprocesses, parses configurations (arcality.config.json), and manages the CLI spinner aesthetic using @clack/prompts.
2. The Vision Engine: Instead of capturing raw DOM, Arcality strips out CSS/JS noise and builds an Interactive Component Tree using aria-labels and roles.
3. The Cognitive Gateway (AIAgentHelper): Handles bidirectional communication with the central AI Brain. It uses advanced recursive Tool Calling to perform UI actions (click, type, scroll) and Forensic actions (capture_console_errors).
4. Skill Injection (.agents/skills/): At runtime, the agent injects external E2E standards directly into the System Prompt to enforce strict QA policies and intelligent locator strategies.
5. The Reporter: A custom execution reporter (ArcalityReporter.ts) that filters out robotic hooks and renders the Agent's pure cognitive decision tree into an HTML dashboard.

📁 Configuration (arcality.config.json)

When you run arcality init, a configuration is generated in your project root.

{
  "project": {
    "name": "PortalAdminQA",
    "baseUrl": "https://dev.arcadial.lat",
    "frameworkDetected": "Next.js"
  },
  "auth": {
    "username": "qa_user",
    "credentialsSource": "env"
  },
  "runtime": {
    "yamlOutputDir": "./.arcality"
  }
}

All reports, saved YAML missions, and runtime context are cleanly isolated inside your project's ./.arcality/ output directory.