Skip to main content

Tacl Genie 🧞

Open Beta Free to Use

AI-powered browser test automation tool that uses natural language to create and run end-to-end tests.

Overview​

Tacl Genie is an AI-powered browser test automation tool that allows you to create and run end-to-end tests using natural language. Instead of writing complex code, you simply describe what you want to test in plain English, and Tacl Genie handles the automation for you.

Installation​

Prerequisites​

  1. Create an account and a project at app.tacl.io to get your API key
  2. Install Node.js (version 18 or higher):
    • Download and follow the installation instructions from nodejs.org

Install Tacl Genie​

Install Tacl Genie:

npm install @tacl/genie@beta

Install Playwright Browsers​

After installation, install the required browsers:

npx playwright install

Quick Start​

  1. Get your API key from app.tacl.io (docs reference) (API keys are project-specific)

  2. Create a .env file in your project root:

# .env
TACL_API_KEY=your_api_key_here
  1. Create a tacl test file in the tacl-tests folder:
mkdir tacl-tests
  1. Create your first test - Create a file like tacl-tests/login.tacl:
Fill username in the email field
Fill password in the password field
Click the Login button
Verify that the dashboard is visible
  1. Run your test:
npx @tacl/genie --testcaseId login --startUrl https://example.com

Note: testcaseId is the name of the file (without extension)

Command Line Usage​

Basic Syntax​

npx @tacl/genie [options]

Required Options​

  • --testcaseId <filename> - Name of the tacl test file (without .tacl extension)
  • --startUrl <url> - Starting URL for the test

Optional Options​

  • --apiKey <env_var_name> - Environment variable name containing your API key (default: TACL_API_KEY)
  • --version - Display version information
  • --help - Show help information

Examples​

# Basic test run
npx @tacl/genie --testcaseId login --startUrl https://myapp.com

# Run with custom API key environment variable
npx @tacl/genie --testcaseId checkout --startUrl https://shop.com --apiKey MY_CUSTOM_API_KEY

💡 Tip: Use custom api keys if you are automating test cases for multiple projects.

Tacl Test Files​

Tacl files use natural language to describe test steps. Create .tacl files in the tacl-tests folder. Simply write what you want the AI to do in plain English.

🪄 Writing Natural Language Tests​

Write your test steps in plain English. Tacl Genie will understand and turn them into automated actions.

💡 General guidelines for better results:

  • ✍️ Prefer one step per line
    Keep each test step on a new line. You can combine actions if they happen on the same screen
    Example: "Enter username and password"

  • 🧭 Use clear actions
    Words like click, fill, select, or check help Genie know exactly what to do.

  • 📍 Add hints about element placement
    If you can, mention where the element is - like "in the navbar", "top right", or "inside the dropdown" - especially if there are similar elements on the page.

  • 🧪 Describe what to verify
    When adding validations, use phrases like "verify success message is visible" or "check if the button is disabled" to help Genie understand assertions.

  • 🆔 Use visible labels or text
    Refer to buttons, links, and fields by the text users actually see - it helps Genie locate the right element.

  • 🧾 Be consistent with naming
    If you refer to something as "Pricing page" in one step, keep the same term in later steps (instead of switching to "Plan screen").

  • 🎯 Avoid vague language
    Instead of saying "Go to next screen", say "Click the 'Next' button" for better accuracy.

Example Tacl File​

Create tacl-tests/ecommerce.tacl:

Click Sign In
Fill user@example.com in email field
Fill mypassword123 in password field
Click Login button
Verify that My Account is visible
Click Add to Cart on the first product
Click View Cart
Verify that cart has 1 item
Click Checkout
Fill John Doe in name field
Fill 123 Main St in address field
Fill 12345 in zip code field
Click Place Order
Verify that order confirmation is visible

Environment Variables for Sensitive Data​

Use environment variables to keep sensitive data secure:

  1. Add entries to .env file in your project root:
# .env
username=your_username_here
password=your_password_here
email=your_email@example.com
  1. Use ${variable} syntax in your tacl files:
Fill ${username} in username field
Fill ${password} in password field
Fill ${email} in email field

The environment variables are replaced during execution and never sent to external services.

Configuration​

API Key Setup​

  1. Get your API key from app.tacl.io (docs reference) (API keys are project-specific)

  2. Set the environment variable:

# .env
TACL_API_KEY=your_api_key_here

Using Your Own OpenAI API Key​

If you want to use your own OpenAI API key instead of tacl's service, you can configure it:

# .env
AI_PROVIDER=openai
OPENAI_API_KEY=your_openai_key

Project Structure​

your-project/
├── tacl-tests/
│   ├── login.tacl
│   ├── signup.tacl
│   └── checkout.tacl
├── .env                    # Environment variables
└── results/               # Test results (auto-created)

Advanced Features​

Custom API Key Variable​

Use a different environment variable name for your API key:

npx @tacl/genie --testcaseId test --startUrl https://example.com --apiKey MY_CUSTOM_KEY

Troubleshooting​

Common Issues​

  1. "API key not found"

    • Make sure your API key environment variable is set
    • Check that the variable name matches what you specified with --apiKey

  2. "Test file not found"

    • Ensure your .tacl file exists in the tacl-tests folder
    • Check that the filename matches your --testcaseId parameter

  3. "Browser not launching"

    • Check your internet connection
    • Verify the start URL is accessible

Getting Help​

# Show help
npx @tacl/genie --help

# Show version
npx @tacl/genie --version

Examples​

Login Test​

tacl-tests/login.tacl:

Fill ${username} in username field
Fill ${password} in password field
Click Login button
Verify that dashboard is visible

E-commerce Flow​

tacl-tests/purchase.tacl:

Click on the first product
Click Add to Cart
Click View Cart
Verify that cart has 1 item
Click Checkout
Fill ${email} in email field
Fill ${address} in address field
Click Complete Purchase
Verify that order confirmation is visible

Limitations​

Current Limitations​

Elements inside modals or popups may not scroll properly Genie currently supports page-level scrolling only. If an element is inside a scrollable modal, it may not be reached.

Limited support for complex layouts Elements inside iframes, browser tabs are not currently supported. Standard buttons, links, text inputs, etc. work best.

No scroll memory during re-runs When re-running a test on dynamic pages, previous scroll positions aren't remembered - this can affect behavior if the element was not initially in view.

Accuracy on complex websites Accuracy on complex websites like heavy e-commerce or shopping websites may be reduced. Tacl Genie will retry and attempt to resolve issues automatically. If problems persist, fine-tuning your prompts with more specific details can improve results.

Beta Access​

Tacl Genie is currently in open beta and completely free to use.

We're actively improving the product based on community feedback.
In the future, Tacl Genie will transition to a paid offering - but we plan to offer a generous free tier, and early users will be prioritized for rewards and discounts.

Your input during this beta phase is truly appreciated!

💬 Feedback & Contact​

We'd love to hear from you!
Whether you have ideas, encounter issues, or just want to share how you're using Tacl Genie - every message helps us improve.

📫 Get in touch:​

🌐 Follow us:​