Skip to main content
This guide covers setting up OpenTester for local development, whether you’re contributing to the project or running a self-hosted instance.

​
Prerequisites

  • Python 3.9+ (for backend)
  • Node.js 18+ (for MCP server)
  • Google Gemini API Key (for AI features)
  • Android SDK and ADB (see Android Setup)

​
Backend Setup

The backend handles test orchestration and coordination using Google’s ADK.

​
Step 1: Clone the Repository

git clone https://github.com/andresuarezz26/OpenTester.git
cd OpenTester

​
Step 2: Set Up Python Environment

cd backend
python -m venv venv
Activate the virtual environment: 
source venv/bin/activate

​
Step 3: Install Dependencies

pip install -r requirements.txt

​
Step 4: Configure Environment

Create a .env file in the backend directory: 
GEMINI_API_KEY=your-api-key-here
BACKEND_PORT=8080
BACKEND_HOST=127.0.0.1
Get your Gemini API Key:
  1. Go to Google AI Studio
  2. Click “Create API Key”
  3. Copy the key and paste into your .env file

​
Step 5: Start the Backend

uvicorn main:app --port 8080 --reload
You should see: 
Uvicorn running on http://127.0.0.1:8080
The --reload flag auto-restarts the server when you change code—great for development.

​
MCP Server Setup

The MCP server acts as the interface between AI tools (Claude Code, Gemini CLI) and the backend.

​
Step 1: Navigate to MCP Server Directory

From your OpenTester repository: 
cd mcp-server

​
Step 2: Install Dependencies

npm install

​
Step 3: Configure Backend URL

Create a .env file in the mcp-server directory: 
BACKEND_URL=http://127.0.0.1:8080
By default, it points to localhost, but you can override it if needed.

​
Step 4: Start the MCP Server

For development with auto-reload: 
npm start
Or build and run: 
npm run build
npm run start:prod

​
Connect Everything

Now you have both services running locally. Update your AI tool configuration to use the local backend.

​
Claude Code

Edit your Claude Code MCP configuration to point to the local backend: 
{
  "mcpServers": {
    "openTester": {
      "command": "npx",
      "args": ["-y", "opentester-mcp-server"],
      "env": {
        "BACKEND_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

​
Gemini CLI

Edit your Gemini CLI settings: 
{
  "mcpServers": {
    "openTester": {
      "command": "npx",
      "args": ["-y", "opentester-mcp-server"],
      "env": {
        "BACKEND_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

​
Development Workflow

​
Testing Your Changes

1

Make code changes

Edit files in the backend or mcp-server directories.
2

Auto-reload

Both servers support auto-reload:
  • Backend: --reload flag in uvicorn
  • MCP Server: npm start with nodemon
3

Test in your AI tool

Restart your AI tool if needed, then run commands to test.
4

Check logs

Monitor the terminal where your services are running for errors.

​
Common Development Commands

Backend: 
cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn main:app --port 8080 --reload
MCP Server: 
cd mcp-server
npm start
Kill a port if it’s stuck: 
lsof -ti:8080 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :8080   # Windows (find PID then taskkill)

​
Debugging

​
Backend Logs

The backend logs are printed to the terminal. Look for:
  • Request/response messages
  • API errors
  • Python tracebacks

​
MCP Server Logs

The MCP server also logs to the terminal. Check for:
  • MCP tool calls
  • Connection messages
  • Error messages

​
Enable Verbose Logging

Backend: 
export LOG_LEVEL=DEBUG
uvicorn main:app --port 8080 --reload
MCP Server: 
export DEBUG=opentester:*
npm start

​
Database & State

The backend may use local storage or database files. By default, they’re stored in:
  • backend/data/ (for local files)
  • Or a local database like SQLite
Clean up state between tests: 
rm -rf backend/data/*

​
Stopping Services

To stop the backend or MCP server:
  • Press Ctrl+C in the terminal where it’s running
  • Or kill the process by port (see “Common Development Commands” above)

​
Running in Production Mode

For testing how it would run in production: Backend: 
uvicorn main:app --host 0.0.0.0 --port 8080
MCP Server: 
npm run build
npm run start:prod

​
Using Docker (Optional)

If you prefer Docker: Backend: 
cd backend
docker build -t opentester-backend .
docker run -p 8080:8080 -e GEMINI_API_KEY=your-key opentester-backend
MCP Server: 
cd mcp-server
docker build -t opentester-mcp .
docker run -e BACKEND_URL=http://host.docker.internal:8080 opentester-mcp

​
Troubleshooting

Another process is using the port. Kill it:
# macOS/Linux
lsof -ti:8080 | xargs kill -9

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F
Or use a different port:
uvicorn main:app --port 8081 --reload
Make sure your .env file exists in the backend directory and has the key:
cat backend/.env
Or set it in your terminal:
export GEMINI_API_KEY=your-key
Your Python virtual environment might not be active:
# macOS/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate
Then try again.
Check that:
  1. Backend is running at http://127.0.0.1:8080
  2. BACKEND_URL env var is set correctly in MCP server
  3. No firewall is blocking localhost
  4. Check logs for connection errors
Make sure you’ve installed dependencies:
npm install
And check your Node.js version:
node --version  # Should be 18+

​
Contributing

When contributing to OpenTester:
  1. Create a feature branch
  2. Make your changes locally
  3. Test thoroughly using the local setup
  4. Commit and push to your fork
  5. Open a pull request
For more details, see CONTRIBUTING.md in the repository.

​
Need Help?