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

2. Initialize your project

Run the setup wizard to connect your project and generate the configuration.

npx arcality init

3. Run your first mission

# Open interactive menu
npx arcality

# Or run directly (Ghost Mode)
npx arcality run

📦 Updating Arcality

Run the following to get the latest version:

npm update @arcadialdev/arcality

⚙️ Configuration (arcality.config.json)

After initializing with npx arcality init, a config file is created in the project root. Edit it to set your project name, base URL, and authentication details. The CLI reads this file on every run, ensuring consistent environment variables.

💻 CLI Commands Cheatsheet

The Arcality flow is designed to be used globally or project-wide via npx. Below are all currently supported commands:

| Command | Description | Internal Behavior | | :--- | :--- | :--- | | npx arcality | Interactive MenuLaunches a visual menu in the terminal to guide the user. | Prompts for the Mission to execute. Ideal for new users who want a guided experience. | | npx arcality init | Initial ConfigurationConnects the current project to Arcadial. | Prompts for your API Key and Project ID, generates arcality.config.json, and validates the portal connection. | | npx arcality run | Mission Runner (Agent Mode)Launches the QA Agent directly. | Skips the interactive menu, scans the package.json ("Ghost Mode"), and unleashes the AI agent. Ideal for CI/CD. | | npx arcality logs | Mission LogsShows the last 3 executed missions in a concise QA-friendly format. | Reads the local .arcality/out mission summaries and displays result, failure reason, last relevant steps, and report path. |

Parallel collection execution

When running a saved collection from the interactive CLI, Arcality can execute multiple missions at the same time. The default is 3 simultaneous missions and the maximum allowed value is 5.

Parallel execution opens multiple independent browser sessions. Arcality cannot validate the tested portal's internal session rules, user lock policies, shared test data constraints, or limits for multiple logins with the same account. If the portal does not support parallel sessions safely, run the collection sequentially with concurrency 1.

🛠️ 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 npx 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.