GECK 🦎 - AI-Native Test Automation (Beta Release)

Supercharge your test automation with Geck, the AI-native platform that writes, runs, and maintains end-to-end tests—right from your VS Code environment or command line.

✅ Self-healing tests: Geck adapts to UI changes without breaking.
🧠 AI-generated test scripts: Describe what you want to test, and let Geck take care of the rest.
🚫 No brittle selectors: Say goodbye to flaky, maintenance-heavy tests.
🖥️ NEW: Command Line Interface (CLI) for CI/CD and automated testing.

🚀 User Quick Start

1. Installation

VS Code Extension:

Install from the VS Code Marketplace.
Open your project folder in VS Code.

Command Line Interface (CLI):

Install globally: npm install -g geck-cli
Or use without installation: npx geck-cli test --token your-token --api-key your-key

2. Authentication

VS Code Extension:

You must provide your email address for authentication. No password is required.
The first time you use Geck, you will be prompted to enter your email in the extension UI.

Command Line Interface (CLI):

IMPORTANT: You must first authenticate through the VS Code extension to get your static token
After authentication in VS Code, you can find your static token in the Settings Panel within the extension
Authentication Options: You can provide credentials either via command line arguments OR environment variables (not both required)
Command Line: --token your-static-token --api-key your-openai-api-key
Environment Variables: GECK_TOKEN=your-static-token and GECK_OPENAI_API_KEY=your-key

3. Setting Up Settings

For the VS Code Extension (Settings Panel)

The extension will prompt you for your OpenAI API key if it is not already set.
All other test execution settings (browser type, run mode, parallelism, UX report, etc.) can be configured in the Geck Settings Panel within VS Code.

Available Settings in the Extension:

Setting Name	Description	Default
Run Mode	Run tests in `headless` mode (no UI) or `browser` mode (visible browser).	`headless`
Max Parallel Tests	Number of tests to run at the same time.	`2`
Browser Type	Choose which browser to use: `chromium`, `firefox`, or `webkit`.	`chromium`
Browser Resolution	Set the screen size for browser during test runs (e.g., `1024x768`).	`1024x768`
AI Test Automation	Choose between Computer Use Agent (CUA) (`cuaModel`), Code Generation & Execution (CGEA) (`generatePlaywrightCode`), or Optimal Algorithm (CGEA & CUA) (`textVisualAutoSwitch`).	`cuaModel`
Generate UX Report	Enable to generate a UX analysis markdown report after test completion.	`false`
Enable Client-Side Login	Enable to detect and execute login actions on the client side.	`false`

4. Creating a Test Case and Categories

In the VS Code Extension:

Click the Geck icon in the VS Code sidebar to open the Geck panel. OR select "Open Geck Sidebar" in command pallet (cmd+shift+p)
In the Geck panel, fill out the test creation form:
- URL: Enter the web address you want to test.
- Test Case Description: Describe what you want to test in plain English.
- Project Name (optional): Use this field to group related test cases (acts as a category).
Click Generate Steps. The extension will use AI to generate a sequence of test steps based on your description.
Review the generated steps; edit/improve steps as needed (you know your product better)
Click Save to store the test case.
- Only after saving will the test case appear in the sidebar list.
- The Execute (Run) button will now be enabled for this test case.

5. Executing Test Cases

In the VS Code Extension:

To run a test case:
1. Find the saved test case in the sidebar list.
2. Click the Execute (Run) button next to the test case to start execution.
3. You can monitor the progress and results in real time.
To run multiple test cases:
- Click Run for project, and all test cases within that project will execute.
- The extension will execute them in parallel (default 2) and show live progress.

6. Viewing Logs

Extension:
Open the Geck Terminal panel in VS Code to see live test output and results.
Log Files:
All logs are saved in .geck/logs/ in your workspace.

7. Add `.geck/` to `.gitignore`

To avoid committing test data, logs, and screenshots, add the following to your .gitignore:

# Geck test data, logs, and screenshots
.geck/

🖥️ Command Line Interface (CLI)

Prerequisites

Before using GECK CLI you need:

Node.js version 18 or higher
Static GECK Token (obtained from VS Code extension authentication)
OpenAI API Key from OpenAI

Getting Started with CLI

Step 1: Get Your Static Token

First, authenticate through VS Code extension (see Authentication section above)
After successful authentication, open the Settings Panel in the VS Code extension
Find your static token in the settings - this is your CLI authentication token
Save this token - you'll need it for CLI usage

Step 2: Set Up Authentication

Choose ONE of these options:

Option 1: Command Line Arguments

geck test --token your-static-token --api-key your-openai-api-key

Option 2: Environment Variables Create a file called .env in your project:

GECK_TOKEN=your-static-token
GECK_OPENAI_API_KEY=your-openai-api-key

Then run:

geck test

Note: You don't need both - choose either command line arguments OR environment variables.

Running Tests with CLI

Basic Usage

# Run all tests
geck test --token your-token --api-key your-key

Browser Mode (for debugging)

# Run tests with visible browser window
geck test --token your-token --api-key your-key --run-mode browser

Headless Mode (for CI/CD)

# Run tests in background without visible browser
geck test --token your-token --api-key your-key --run-mode headless

Different Browsers

# Run tests in different browsers
geck test --token your-token --api-key your-key --browser chromium
geck test --token your-token --api-key your-key --browser firefox
geck test --token your-token --api-key your-key --browser webkit

Custom Resolution

# Run tests with specific browser resolution
geck test --token your-token --api-key your-key --resolution "Desktop Full HD 1920×1080"

Enable UX Reports

# Generate UX analysis reports
geck test --token your-token --api-key your-key --ux-report

Custom Log Level

# Set logging level for more or less output
geck test --token your-token --api-key your-key --log-level debug
geck test --token your-token --api-key your-key --log-level info
geck test --token your-token --api-key your-key --log-level error

CLI Command Options

Required Options

--token: Your static GECK authentication token (from VS Code extension)
--api-key: Your OpenAI API key

Optional Options

--run-mode: Set run mode to headless or browser
--browser: Set browser type to chromium, firefox, or webkit
--resolution: Set browser resolution
--ai-mode: Set AI mode to cuaModel, generatePlaywrightCode, or textVisualAutoSwitch
--log-level: Set log level to trace, debug, info, warn, or error
--no-analytics: Disable analytics
--ux-report: Enable UX report generation
--workspace: Set workspace path
--css-framework: Set CSS framework
--domain-type: Set domain type
--ui-library: Set UI library

Environment Variables

You can set these environment variables instead of using command line arguments:

GECK_TOKEN: Your static GECK authentication token
GECK_OPENAI_API_KEY: Your OpenAI API key
GECK_RUN_MODE: Run mode
GECK_BROWSER_TYPE: Browser type
GECK_BROWSER_RESOLUTION: Browser resolution
GECK_AI_TEST_AUTOMATION: AI test automation mode
GECK_LOG_LEVEL: Log level
GECK_ENABLE_ANALYTICS: Enable analytics
GECK_GENERATE_UX_REPORT: Enable UX report generation
GECK_CSS_FRAMEWORK: CSS framework
GECK_DOMAIN_TYPE: Domain type
GECK_UI_LIBRARY: UI library
GECK_APPLICATION_CONTEXT: Application context
GECK_TECHNICAL_NOTES: Technical notes
GECK_ENABLE_OPTIMIZATIONS: Enable optimizations

GitHub Actions Integration

You can integrate GECK CLI into your GitHub Actions workflows. Set up your secrets in GitHub repository settings:

Go to your GitHub repository
Click Settings tab
Click Secrets and variables then Actions
Click New repository secret
Add these secrets:
- GECK_TOKEN: your-static-token-from-vscode-extension
- OPENAI_API_KEY: your-openai-api-key

Then use these secrets in your workflow environment variables.

CLI Test Results

Success Output

Loading CLI configuration...
CLI configuration loaded successfully
Starting test: login-test
Test login-test completed successfully
CLI test run completed successfully

Failure Output

Loading CLI configuration...
CLI configuration loaded successfully
Starting test: login-test
Test login-test failed, stopping execution
CLI test run failed - one or more tests failed
Exiting immediately due to test failure

Exit Codes

0: All tests passed
1: One or more tests failed

CLI Troubleshooting

Common Issues

Authentication token required error
- Make sure you provide --token argument or set GECK_TOKEN environment variable
- Remember: You must first authenticate through VS Code extension and find your static token in the Settings Panel
OpenAI API key required error
- Make sure you provide --api-key argument or set GECK_OPENAI_API_KEY environment variable
Test cases not found error
- Make sure test/testcases.json file exists and has valid JSON
Workspace path does not exist error
- Make sure the workspace path you specified exists

Getting Help

Run this command to see all available options:

geck --help

CLI Examples

Local Development

geck test --token your-token --api-key your-key --run-mode browser

CI/CD Pipeline

geck test --token your-token --api-key your-key --run-mode headless

With Custom Settings

geck test --token your-token --api-key your-key --browser firefox --resolution "Desktop Full HD 1920×1080" --ux-report

CLI Best Practices

Always authenticate through VS Code extension first and get your static token from the Settings Panel
Use headless mode for CI/CD environments
Use browser mode for local development and debugging
Always test against staging environments in CI/CD
Keep test cases in version control
Never commit .env files with real credentials
Use GitHub Secrets for CI/CD authentication
Test locally before pushing to CI/CD
Choose either command line arguments OR environment variables - you don't need both

✨ Key Features

Capability	Description
Webview UI	Create & manage test cases with a form/table inside a VS Code panel.
Command Line Interface	Run tests from command line for CI/CD integration and automated workflows.
AI‑authored steps	OpenAI (o3‑mini / gpt‑4o‑mini) converts natural‑language descriptions into step‑by‑step JSON test scripts.
Playwright Runner	One‑click "Run" launches Chromium at the requested URL, executes the generated script, and stores run metadata.
Persistent workspace storage	Test cases are saved in `test/` folder and test runs in `.geck/` folder inside the workspace.
GitHub Actions Integration	Seamless CI/CD integration with GitHub Actions workflows.
Multi‑browser Support	Test across Chromium, Firefox, and WebKit browsers.
UX Analysis Reports	Generate detailed UX analysis reports after test completion.
Tailwind + Lucide UI kit	Clean, dark‑theme‑aware styling without external CSS frameworks.
Fully‑typed TS codebase	Strict `typescript`, ESLint, Webpack build pipeline.

🛠 Requirements

VS Code Extension

VS Code ≥ 1.85 (the extension targets this API level)
Node ≥ 18 (to build & run scripts)
Playwright: installed automatically on first run (npx playwright install), or install browsers manually.
OpenAI API key – exported as OPENAI_API_KEY in your shell, and if you want to use CUA models, make sure you have access to those models.

Command Line Interface

Node.js ≥ 18 (required for CLI execution)
Static GECK Token – obtained from VS Code extension authentication
OpenAI API Key – for AI test generation and execution
Playwright: installed automatically on first CLI run (npx playwright install)

🖥️ Using Geck

VS Code Extension

Open a workspace folder – Geck stores files next to your source.
Execute "Geck: Open Geck Panel".
In the form:
- Enter a URL to test.
- Describe the test case in plain English.
- (Optional) toggle Authentication and supply credentials.
Press Submit → a new row appears in the table with status Queued.
Click Run to launch Playwright. Progress & status update live.
Delete or view details as needed.

Command Line Interface

First authenticate through VS Code extension to get your static token
Create test cases in test/testcases.json file (or use existing ones from VS Code)
Set up authentication via command line arguments or environment variables
Run tests with geck test command
View results in .geck/ folder

Where is my data?

Test cases → <workspace>/test/{project-name}-testcases.json
Test runs → <workspace>/.geck/testruns.json

Delete the folder to reset everything.

⚙️ Configuration

VS Code Extension

Once Geck is installed, you can provide OPENAI_API_KEY which will be securely saved within your VS code (SecretStorage in VS Code) and will stay there. Just make sure it has access to O3, and CUA based models.

Command Line Interface

Authentication: Use the static token obtained from VS Code extension authentication
OpenAI API Key: Provide via --api-key argument or GECK_OPENAI_API_KEY environment variable
All settings: Can be configured via command line arguments or environment variables (see CLI section above)

Geck (Beta)

Geck

GECK 🦎 - AI-Native Test Automation (Beta Release)

🚀 User Quick Start

1. Installation

2. Authentication

3. Setting Up Settings

For the VS Code Extension (Settings Panel)

4. Creating a Test Case and Categories

5. Executing Test Cases

6. Viewing Logs

7. Add .geck/ to .gitignore

🖥️ Command Line Interface (CLI)

Prerequisites

Getting Started with CLI

Step 1: Get Your Static Token

Step 2: Set Up Authentication

Running Tests with CLI

Basic Usage

Browser Mode (for debugging)

Headless Mode (for CI/CD)

Different Browsers

Custom Resolution

Enable UX Reports

Custom Log Level

CLI Command Options

Required Options

Optional Options

Environment Variables

GitHub Actions Integration

CLI Test Results

Success Output

Failure Output

Exit Codes

CLI Troubleshooting

Common Issues

Getting Help

CLI Examples

Local Development

CI/CD Pipeline

With Custom Settings

CLI Best Practices

✨ Key Features

🛠 Requirements

VS Code Extension

Command Line Interface

🖥️ Using Geck

VS Code Extension

Command Line Interface

Where is my data?

⚙️ Configuration

VS Code Extension

Command Line Interface

7. Add `.geck/` to `.gitignore`