Feat: Shortest (#80)

# AI-Powered E2E Testing Framework

Addresses: #69

This PR introduces a complete end-to-end testing framework powered by
Claude AI. The framework enables writing tests in natural language and
executes them through AI-driven browser automation.

## Key Features
- Natural language test definitions using a fluent API
- AI-powered test execution using Claude computer use
- Automated browser interaction with precise coordinate handling
- Detailed test reporting with pass/fail status

## Technical Highlights
- Direct integration with Anthropic's Claude API
- Playwright-based browser automation
- Coordinate scaling system for reliable element targeting
- Visual mouse tracking for debugging
- Modular architecture with clear separation of concerns

Author: slavingia

.gitignore

@@ -1,7 +1,8 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
 # dependencies
-/node_modules
+node_modules/
+.pnpm-store/
 /.pnp
 .pnp.js
 .yarn/install-state.gz
@@ -16,6 +17,10 @@
 # production
 /build
 
+# Build outputs
+dist/
+*.tsbuildinfo
+
 # misc
 .DS_Store
 *.pem
@@ -40,4 +45,7 @@ next-env.d.ts
 # docker
 .docker
 docker-compose.override.yml
-docker-compose.yml
+docker-compose.yml
+
+# screenshots
+screenshots/

README.md

@@ -4,7 +4,7 @@
 
 ## Local Development Setup Guide
 
-This guide will help you set up the Shortest project for local development.
+This guide will help you set up the Shortest web app for local development.
 
 ### Prerequisites
 
@@ -123,8 +123,51 @@ Open [http://localhost:3000](http://localhost:3000) in your browser to see the a
 
 ### Running Tests
 
-To run specs:
+To run unit tests:
 
 ```bash
 pnpm vitest
 ```
+
+
+## Setup Guide for Running and Building Shortest Package Locally
+   
+When running `pnpm install` in the root, the `shortest` package will built and added in the `node_modules` folder. However, in order to run the tests locally using `pnpm test` or `shortest cli`, you need to do the following: 
+
+### Prerequisites
+
+- Playwright 
+- Chromium
+
+### Install Playwright and build package
+
+```bash
+pnpm add playwright
+pnpm exec playwright install 
+
+# to install shortest package
+pnpm install
+```
+
+### Setup Shortest CLI
+```bash
+# packages/shortest
+cd packages/shortest
+pnpm link --global
+
+# root
+cd ../..
+pnpm link --global shortest
+```
+
+## Run Tests
+You can either run tests using the `shortest` cli:
+```bash
+shortest
+```
+
+or use the `pnpm` command:
+
+```bash
+pnpm test
+```

app/__tests__/home.test.ts

@@ -0,0 +1,14 @@
+import { afterAll, beforeAll, define, UITestBuilder } from 'shortest';
+
+interface loginButton {
+  url: string;
+}
+
+define('Validate login button in home page', () => {
+
+  new UITestBuilder<loginButton>('/')
+    .test('Validate login button is visible and works')
+    .given('baseUrl', { url: 'http://localhost:3000' })
+    .expect('Should redirect to login page')
+
+});

app/__tests__/login.test.ts

@@ -0,0 +1,21 @@
+import { afterAll, beforeAll, define, UITestBuilder } from 'shortest';
+
+interface LoginState {
+  username: string;
+  password: string;
+}
+
+define('Validate login feature implemented with Clerk', () => {
+
+  new UITestBuilder<LoginState>('/')
+    .test('Login to the app using Email and Password')
+    .given('username and password', { username: 'argo.mohrad@gmail.com', password: 'Shortest1234' })
+    .when('Logged in, click on view dashboard button')
+    .expect('should successfully redirect to /')
+
+    // new UITestBuilder<LoginState>('/')
+    // .test('Login to the app using Google account')
+    // .given('username and password', { username: 'test', password: 'test' })
+    // .expect('should successfully redirect to /dashboard')
+
+});

package.json

@@ -79,6 +79,7 @@
     "js-yaml": "^4.1.0",
     "jsdom": "^25.0.1",
     "smee-client": "^2.0.3",
-    "vitest": "^2.1.1"
+    "vitest": "^2.1.1",
+    "shortest": "workspace:*"
   }
 }

packages/shortest/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "shortest",
+  "version": "0.0.1",
+  "description": "AI-powered natural language end-to-end testing framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "shortest": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && pnpm build:types && pnpm build:js && pnpm build:cli",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build:js": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --external:fsevents --external:chokidar --external:glob --external:esbuild --external:playwright --external:playwright-core --external:chromium-bidi",
+    "build:cli": "esbuild src/cli/bin.ts --bundle --platform=node --format=esm --outfile=dist/cli/bin.js --external:fsevents --external:chokidar --external:glob --external:esbuild --banner:js='import { createRequire } from \"module\"; const require = createRequire(import.meta.url); import { fileURLToPath } from \"url\"; const __filename = fileURLToPath(import.meta.url); import { dirname } from \"path\"; const __dirname = dirname(__filename);' --external:events --external:path --external:fs --external:util --external:stream --external:os --external:assert --external:url",
+    "dev": "pnpm build:types --watch",
+    "prepare": "pnpm exec playwright install && pnpm build && chmod +x dist/cli/bin.js",
+    "preinstall": "pnpm build",
+    "postinstall": "pnpm exec playwright install",
+    "test:ai": "tsx scripts/test-ai.ts",
+    "test:browser": "tsx scripts/test-browser.ts",
+    "test:coordinates": "tsx scripts/test-coordinates.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.32.0",
+    "ai": "^3.4.31",
+    "chokidar": "^3.5.3",
+    "chromium-bidi": "^0.5.2",
+    "esbuild": "^0.20.1",
+    "glob": "^10.3.10",
+    "picocolors": "^1.0.0",
+    "playwright": "^1.42.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "tsx": "^4.7.1",
+    "typescript": "~5.6.2"
+  }
+}