Welcome to the OpenHands tutorial library. These tutorials show you how to use OpenHands for common development tasks, from testing to feature development. Each tutorial includes example prompts, expected workflows, and tips for success.
Categories Overview
| Category | Best For | Complexity |
|---|
| Testing | Adding tests, improving coverage | Simple to Medium |
| Data Analysis | Processing data, generating reports | Simple to Medium |
| Web Scraping | Extracting data from websites | Medium |
| Code Review | Analyzing PRs, finding issues | Simple |
| Bug Fixing | Diagnosing and fixing errors | Medium |
| Feature Development | Building new functionality | Medium to Complex |
For in-depth guidance on specific use cases, see our Use Cases section which includes detailed workflows for Code Review, Incident Triage, and more. Task Complexity Guidance
Before starting, assess your task’s complexity:
Simple tasks (5-15 minutes):
- Single file changes
- Clear, well-defined requirements
- Existing patterns to follow
Medium tasks (15-45 minutes):
- Multiple file changes
- Some discovery required
- Integration with existing code
Complex tasks (45+ minutes):
- Architectural changes
- Multiple components
- Requires iteration
Start with simpler tutorials to build familiarity with OpenHands before tackling complex tasks.
Best Use Cases
OpenHands excels at:
- Repetitive tasks: Boilerplate code, test generation
- Pattern application: Following established conventions
- Analysis: Code review, debugging, documentation
- Exploration: Understanding new codebases
Example Tutorials by Category
Testing
Tutorial: Add Unit Tests for a Module
Goal: Achieve 80%+ test coverage for a service module
Prompt:
Add unit tests for the UserService class in src/services/user.js.
Current coverage: 35%
Target coverage: 80%
Requirements:
1. Test all public methods
2. Cover edge cases (null inputs, empty arrays, etc.)
3. Mock external dependencies (database, API calls)
4. Follow our existing test patterns in tests/services/
5. Use Jest as the testing framework
Focus on these methods:
- createUser()
- updateUser()
- deleteUser()
- getUserById()
- Analyzes the UserService class
- Identifies untested code paths
- Creates test file with comprehensive tests
- Mocks dependencies appropriately
- Runs tests to verify they pass
Tips:
- Provide existing test files as examples
- Specify the testing framework
- Mention any mocking conventions
Tutorial: Add Integration Tests for an API
Goal: Test API endpoints end-to-end
Prompt:
Add integration tests for the /api/products endpoints.
Endpoints to test:
- GET /api/products (list all)
- GET /api/products/:id (get one)
- POST /api/products (create)
- PUT /api/products/:id (update)
- DELETE /api/products/:id (delete)
Requirements:
1. Use our test database (configured in jest.config.js)
2. Set up and tear down test data properly
3. Test success cases and error cases
4. Verify response bodies and status codes
5. Follow patterns in tests/integration/
Data Analysis
Tutorial: Create a Data Processing Script
Goal: Process CSV data and generate a report
Prompt:
Create a Python script to analyze our sales data.
Input: sales_data.csv with columns: date, product, quantity, price, region
Requirements:
1. Load and validate the CSV data
2. Calculate:
- Total revenue by product
- Monthly sales trends
- Top 5 products by quantity
- Revenue by region
3. Generate a summary report (Markdown format)
4. Create visualizations (bar chart for top products, line chart for trends)
5. Save results to reports/ directory
Use pandas for data processing and matplotlib for charts.
- Creates a Python script with proper structure
- Implements data loading with validation
- Calculates requested metrics
- Generates formatted report
- Creates and saves visualizations
Tutorial: Database Query Analysis
Goal: Analyze and optimize slow database queries
Prompt:
Analyze our slow query log and identify optimization opportunities.
File: logs/slow_queries.log
For each slow query:
1. Explain why it's slow
2. Suggest index additions if helpful
3. Rewrite the query if it can be optimized
4. Estimate the improvement
Create a report in reports/query_optimization.md with:
- Summary of findings
- Prioritized recommendations
- SQL for suggested changes
Web Scraping
Tutorial: Build a Web Scraper
Goal: Extract product data from a website
Prompt:
Create a web scraper to extract product information from our competitor's site.
Target URL: https://example-store.com/products
Extract for each product:
- Name
- Price
- Description
- Image URL
- SKU (if available)
Requirements:
1. Use Python with BeautifulSoup or Scrapy
2. Handle pagination (site has 50 pages)
3. Respect rate limits (1 request/second)
4. Save results to products.json
5. Handle errors gracefully
6. Log progress to console
Include a README with usage instructions.
- Specify rate limiting requirements
- Mention error handling expectations
- Request logging for debugging
Code Review
Tutorial: Security-Focused Code Review
Goal: Identify security vulnerabilities in a PR
Prompt:
Review this pull request for security issues:
Focus areas:
1. Input validation - check all user inputs are sanitized
2. Authentication - verify auth checks are in place
3. SQL injection - check for parameterized queries
4. XSS - verify output encoding
5. Sensitive data - ensure no secrets in code
For each issue found, provide:
- File and line number
- Severity (Critical/High/Medium/Low)
- Description of the vulnerability
- Suggested fix with code example
Output format: Markdown suitable for PR comments
Goal: Identify performance issues in code
Prompt:
Review the OrderService class for performance issues.
File: src/services/order.js
Check for:
1. N+1 database queries
2. Missing indexes (based on query patterns)
3. Inefficient loops or algorithms
4. Missing caching opportunities
5. Unnecessary data fetching
For each issue:
- Explain the impact
- Show the problematic code
- Provide an optimized version
- Estimate the improvement
Bug Fixing
For production incident investigation and automated error analysis, see the Incident Triage Use Case which covers integration with monitoring tools like Datadog. Tutorial: Fix a Crash Bug
Goal: Diagnose and fix an application crash
Prompt:
Fix the crash in the checkout process.
Error:
TypeError: Cannot read property 'price' of undefined
at calculateTotal (src/checkout/calculator.js:45)
at processOrder (src/checkout/processor.js:23)
Steps to reproduce:
1. Add item to cart
2. Apply discount code "SAVE20"
3. Click checkout
4. Crash occurs
The bug was introduced in commit abc123 (yesterday's deployment).
Requirements:
1. Identify the root cause
2. Fix the bug
3. Add a regression test
4. Verify the fix doesn't break other functionality
- Analyzes the stack trace
- Reviews recent changes
- Identifies the null reference issue
- Implements a defensive fix
- Creates test to prevent regression
Tutorial: Fix a Memory Leak
Goal: Identify and fix a memory leak
Prompt:
Investigate and fix the memory leak in our Node.js application.
Symptoms:
- Memory usage grows 100MB/hour
- After 24 hours, app becomes unresponsive
- Restarting temporarily fixes the issue
Suspected areas:
- Event listeners in src/events/
- Cache implementation in src/cache/
- WebSocket connections in src/ws/
Analyze these areas and:
1. Identify the leak source
2. Explain why it's leaking
3. Implement a fix
4. Add monitoring to detect future leaks
Feature Development
Tutorial: Add a REST API Endpoint
Goal: Create a new API endpoint with full functionality
Prompt:
Add a user preferences API endpoint.
Endpoint: /api/users/:id/preferences
Operations:
- GET: Retrieve user preferences
- PUT: Update user preferences
- PATCH: Partially update preferences
Preferences schema:
{
theme: "light" | "dark",
notifications: { email: boolean, push: boolean },
language: string,
timezone: string
}
Requirements:
1. Follow patterns in src/api/routes/
2. Add request validation with Joi
3. Use UserPreferencesService for business logic
4. Add appropriate error handling
5. Document the endpoint in OpenAPI format
6. Add unit and integration tests
- Creates route handler following existing patterns
- Implements validation middleware
- Creates or updates the service layer
- Adds error handling
- Generates API documentation
- Creates comprehensive tests
Tutorial: Implement a Feature Flag System
Goal: Add feature flags to the application
Prompt:
Implement a feature flag system for our application.
Requirements:
1. Create a FeatureFlags service
2. Support these flag types:
- Boolean (on/off)
- Percentage (gradual rollout)
- User-based (specific user IDs)
3. Load flags from environment variables initially
4. Add a React hook: useFeatureFlag(flagName)
5. Add middleware for API routes
Initial flags to configure:
- new_checkout: boolean, default false
- dark_mode: percentage, default 10%
- beta_features: user-based
Include documentation and tests.
Contributing Tutorials
Have a great use case? Share it with the community!
What makes a good tutorial:
- Solves a common problem
- Has clear, reproducible steps
- Includes example prompts
- Explains expected outcomes
- Provides tips for success
How to contribute:
- Create a detailed example following this format
- Test it with OpenHands to verify it works
- Submit via GitHub pull request to the docs repository
- Include any prerequisites or setup required
These tutorials are starting points. The best results come from adapting them to your specific codebase, conventions, and requirements.
