Stagehand Localhost Tests

Project to run automated tests with Stagehand against applications on localhost.

🚀 Features

• ✅ AI-powered automated tests using Stagehand
• ✅ Page navigation and verification
• ✅ Form and element interaction
• ✅ Automatic screenshots
• ✅ Colorful logging system

📋 Requirements

• Node.js 18 or higher
• An application running on localhost (port 3000 by default)
• Anthropic API key (for Stagehand AI features)

🔧 Installation

1. Clone or copy this project.
2. Install dependencies:

npm install

3. Copy the example environment file and configure it:

cp .env

4. Edit the .env file and add your Anthropic API key:

ANTHROPIC_API_KEY=your_api_key_here
LOCALHOST_URL=http://localhost:3000
HEADLESS=false
VERBOSE=1

🏃 Usage

Run all tests

npm test

Run in development mode (with ts-node, without compiling)

npm run dev

Run a single test

npm run build
node dist/tests/test-basic-navigation.js

Or in development:

npx ts-node src/tests/test-basic-navigation.ts

Compile the project

npm run build

Clean compiled files

npm run clean

📁 Project Structure

stagehand-localhost-tests/
├── src/
│   ├── tests/                          # Stagehand tests
│   │   ├── test-basic-navigation.ts    # Basic navigation test
│   │   ├── test-form-interaction.ts    # Form interaction test
│   │   ├── test-data-extraction.ts     # AI data extraction test
│   │   └── run-all.ts                  # Runner for all tests
│   ├── utils/                          # Utilities
│   │   ├── stagehand-config.ts         # Stagehand configuration
│   │   └── logger.ts                   # Logging system
│   └── types/                          # TypeScript types (optional)
├── screenshots/                        # Screenshots generated by tests
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🧪 Included Tests

1. Basic Navigation (test-basic-navigation.ts)

• Navigates to the localhost URL
• Verifies the page loads correctly
• Gets the page title
• Takes a screenshot

⚙️ Configuration

Environment Variables

Variable	Description	Default
ANTHROPIC_API_KEY	Anthropic API key (required)	-
LOCALHOST_URL	Base URL of your application	http://localhost:3000
LOCALHOST_PORT	Port of your application	3000
HEADLESS	Run browser in headless mode	false
VERBOSE	Verbosity level (0–2)	1

Customizing Tests

The tests are designed to be easily customizable. You can:

1. Change the URL: Modify LOCALHOST_URL in .env.
2. Adjust routes: Use getLocalhostUrl("/path") in your tests.
3. Modify actions: Change the instructions in act() according to your application.
4. Customize extraction: Adjust the extract() schemas to your needs.

Create a New Test

import { Stagehand } from "@browserbasehq/stagehand";
import { createStagehand, closeStagehand, getLocalhostUrl } from "../utils/stagehand-config";
import { TestLogger } from "../utils/logger";

export async function testMyNewTest(): Promise<boolean> {
  const logger = new TestLogger("My New Test");
  logger.startTest();

  let stagehand: Stagehand | null = null;

  try {
    stagehand = await createStagehand();
    logger.success("Stagehand initialized");

    // Your test code here
    await stagehand.page.goto(getLocalhostUrl("/my-route"));
    
    // ... more actions ...

    logger.endTest(true);
    return true;

  } catch (error) {
    logger.error("Error:", error);
    logger.endTest(false);
    return false;

  } finally {
    if (stagehand) {
      await closeStagehand(stagehand);
    }
  }
}

📸 Screenshots

Screenshots are automatically saved in the screenshots/ folder with descriptive names:

• basic-navigation.png
• form-interaction.png
• data-extraction.png
• And any others you capture in your custom tests

🐛 Troubleshooting

Error: "Cannot find module '@browserbasehq/stagehand'"

Run npm install to install dependencies.

Error: "Missing environment variable: ANTHROPIC_API_KEY"

Make sure you created the .env file and added your API key.

The application is not on port 3000

Change LOCALHOST_URL in your .env file to the correct port.

Tests fail because elements are not found

The example tests use generic instructions. Adjust the act() and extract() instructions according to the real elements in your application.

📚 Resources

• Stagehand documentation
• Anthropic documentation
• Playwright API

📝 Notes

• The tests are designed to run with the browser visible (headless: false) so you can see what’s happening.
• Each test takes screenshots to make debugging easier.
• The logging system uses colors to improve readability.
• Tests run sequentially with small pauses between them.

🤝 Contributing

Feel free to add more tests or improve existing ones according to your application’s needs.

📄 License

MIT