Contributing to OpenTester

Thank you for your interest in the OpenTester project! This document will help you understand how to participate in project development.

Table of Contents

• Development Environment Setup
• Project Structure
• Development Workflow
• Code Standards
• Commit Conventions
• Testing
• Documentation
• Release Process

Development Environment Setup

Prerequisites

• Python 3.13+
• Node.js 18+
• Git
• uv (recommended) or pip

Backend Development Environment

# Clone repository
git clone https://github.com/kznr02/OpenTester.git
cd OpenTester/backend

# Install dependencies using uv (recommended)
uv pip install -e ".[dev]"

# Or using pip
pip install -e ".[dev]"

# Start development server
uv run opentester start

Frontend Development Environment

cd OpenTester/frontend

# Install dependencies
npm install

# Start development server
npm run dev

Verify Environment

# Check environment configuration
opentester doctor

# Run tests
pytest

Project Structure

OpenTester/
├── backend/                 # Python backend
│   ├── opentester/          # Main package
│   │   ├── api/           # REST API
│   │   ├── core/          # Execution engine
│   │   ├── mcp/           # MCP server
│   │   ├── models/        # Data models
│   │   ├── cli.py         # CLI entry
│   │   └── main.py        # FastAPI entry
│   ├── tests/             # Test cases
│   └── pyproject.toml     # Project configuration
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/    # Components
│   │   ├── pages/         # Pages
│   │   ├── stores/        # State management
│   │   └── lib/           # Utilities
│   └── package.json
├── docs/                   # Documentation
└── examples/              # Example files

Development Workflow

1. Create Branch

# Create new branch from main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

# Or fix bug
git checkout -b fix/bug-description

Branch naming conventions:

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test related

2. Development and Testing

# Run tests to ensure no existing functionality is broken
pytest

# Frontend tests
npm run test

3. Submit Changes

# Add changes
git add .

# Commit (follow commit conventions)
git commit -m "feat: add new feature"

# Push to remote
git push origin feature/your-feature-name

4. Create Pull Request

1. Create Pull Request on GitHub
2. Fill in PR description explaining changes and reasons
3. Link related Issues (if any)
4. Wait for code review

Code Standards

Python Code Standards

• Follow PEP 8
• Use type hints
• Functions and classes must have docstrings
• Maximum line length 100 characters

def validate_dsl(dsl_yaml: str) -> ValidationResult:
    """Validate DSL YAML syntax and schema.

    Args:
        dsl_yaml: DSL YAML content to validate

    Returns:
        ValidationResult with success status and error messages
    """
    # Implementation

TypeScript/React Code Standards

• Use TypeScript strict mode
• Use functional components for components
• Props must have type definitions
• Follow hooks rules

interface ProjectCardProps {
  project: Project;
  onDelete?: (id: string) => void;
}

export function ProjectCard({ project, onDelete }: ProjectCardProps) {
  // Component implementation
}

Import Sorting

Python:

# Standard library
import json
from pathlib import Path

# Third-party libraries
import typer
from fastapi import FastAPI

# Local modules
from opentester.models import Project
from opentester.core.storage import ProjectStorage

Commit Conventions

Use Conventional Commits specification:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Type Reference

Type	Description
feat	New features
fix	Bug fixes
docs	Documentation updates
style	Code formatting (no functional changes)
refactor	Code refactoring
test	Test related
chore	Build/tools/configuration

Examples

# New feature
git commit -m "feat: add template management feature"

# Bug fix
git commit -m "fix: fix memory leak in DSL validation"

# Documentation
git commit -m "docs: update MCP interface documentation"

# With scope
git commit -m "feat(mcp): add new tool list interface"

# With body
git commit -m "feat: add execution history persistence

- Add ExecutionStorage class
- Support loading historical execution records
- Auto-save state after each step"

Testing

Backend Testing

# Run all tests
pytest

# Run specific test
pytest tests/test_execution.py

# With coverage
pytest --cov=opentester --cov-report=html

# Debug mode
pytest -v --tb=short

Testing Standards

• Test files start with test_
• Test functions start with test_
• Use pytest fixtures
• Target test coverage > 80%

import pytest
from opentester.core.execution_engine import ExecutionManager

@pytest.fixture
def execution_manager():
    return ExecutionManager()

def test_execution_manager_init(execution_manager):
    assert execution_manager is not None
    assert execution_manager.active_executions == {}

Frontend Testing

# Run tests
npm run test

# Run tests (watch mode)
npm run test:watch

Documentation

Documentation to Update

When modifying code, please check if the following documentation needs updating:

1. Code comments - Functions, classes, complex logic
2. README.md - If it affects usage
3. docs/*.md - Related feature documentation
4. CHANGELOG.md - Record changes
5. examples/ - Related examples

Documentation Standards

• Use Markdown format
• Code blocks with language annotation
• Add table of contents (for long documents)
• Use tables for parameters

Release Process

Version Numbering

Use semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible feature additions
• PATCH: Backward-compatible bug fixes

Release Steps

1. Update version number (pyproject.toml)
2. Update CHANGELOG.md
3. Create git tag
4. Build distribution packages
5. Publish to PyPI

# Update version number
# Edit pyproject.toml: version = "0.2.0"

# Update CHANGELOG.md

# Submit changes
git add .
git commit -m "chore: bump version to 0.2.0"

# Create tag
git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0

# Build and publish
cd backend
python -m build
twine upload dist/*

Getting Help

• View Documentation
• Submit Issue
• Join Discussions

Code of Conduct

• Respect all participants
• Accept constructive criticism
• Focus on what's best for the community
• Show empathy

Thank you for contributing to OpenTester!