mirror of
https://github.com/appwrite/appwrite.git
synced 2026-05-26 13:51:13 +00:00
Add agent instructions for screenshot capture using Playwright
Co-authored-by: stnguyen90 <1477010+stnguyen90@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
@@ -15,7 +15,21 @@ Happy contributing!
|
||||
|
||||
## Test Plan
|
||||
|
||||
(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Screenshots may also be helpful.)
|
||||
(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work.)
|
||||
|
||||
## Screenshots
|
||||
|
||||
**Required for UI changes**: If this PR includes visual/UI changes, please include before/after screenshots.
|
||||
See [screenshot guide](.github/agents/screenshot-guide.md) for instructions on using Playwright to capture screenshots.
|
||||
|
||||
- [ ] Screenshots included (or not applicable)
|
||||
|
||||
<!--
|
||||
To capture screenshots:
|
||||
1. Install Playwright: npm install -D @playwright/test && npx playwright install chromium
|
||||
2. See .github/agents/screenshot-guide.md for example scripts
|
||||
3. Drag and drop screenshot images here
|
||||
-->
|
||||
|
||||
## Related PRs and Issues
|
||||
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# Agent Instructions
|
||||
|
||||
This directory contains instruction files for various automated agents that work with the Appwrite repository.
|
||||
|
||||
## Purpose
|
||||
|
||||
These instruction files provide standardized guidelines for:
|
||||
- AI-powered coding agents (e.g., GitHub Copilot)
|
||||
- Automated workflow agents
|
||||
- Code review assistants
|
||||
- Issue triage bots
|
||||
|
||||
## Available Instructions
|
||||
|
||||
### code-change-agent.md
|
||||
Instructions for agents that make code changes and create pull requests. Includes:
|
||||
- Code change best practices
|
||||
- Testing requirements
|
||||
- **Screenshot capture guidelines using Playwright**
|
||||
- PR submission standards
|
||||
|
||||
## Using These Instructions
|
||||
|
||||
### For Human Contributors
|
||||
While these instructions are primarily for automated agents, human contributors may find them useful as:
|
||||
- Guidelines for creating high-quality PRs
|
||||
- Standards for documenting UI changes
|
||||
- Best practices for testing
|
||||
|
||||
### For Agent Developers
|
||||
When building or configuring automated agents for this repository:
|
||||
1. Review the relevant instruction file for the agent's purpose
|
||||
2. Ensure the agent follows the guidelines, especially screenshot requirements for UI changes
|
||||
3. Test the agent's behavior against these standards before deployment
|
||||
|
||||
## Screenshot Requirements
|
||||
|
||||
**All agents making UI changes MUST capture screenshots** to document visual modifications. See `code-change-agent.md` for detailed instructions on:
|
||||
- When to take screenshots
|
||||
- How to use Playwright for screenshot capture
|
||||
- How to include screenshots in PRs
|
||||
|
||||
## Contributing
|
||||
|
||||
To update or add agent instructions:
|
||||
1. Create or modify the appropriate `.md` file in this directory
|
||||
2. Follow the existing format and structure
|
||||
3. Ensure instructions are clear, actionable, and testable
|
||||
4. Submit a PR with your changes
|
||||
|
||||
## Related Files
|
||||
|
||||
- `.github/workflows/issue-triage.md` - Agentic workflow for issue triage
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md` - PR template that all PRs should follow
|
||||
- `CONTRIBUTING.md` - General contributing guidelines
|
||||
@@ -0,0 +1,205 @@
|
||||
# Code Change Agent Instructions
|
||||
|
||||
## Overview
|
||||
This document provides instructions for agents that make code changes to the Appwrite repository. These instructions ensure consistency and quality across automated code contributions.
|
||||
|
||||
## General Guidelines
|
||||
|
||||
### Code Changes
|
||||
1. Make minimal, focused changes that address the specific issue or requirement
|
||||
2. Follow the existing code style and conventions in the repository
|
||||
3. Ensure all changes are properly tested
|
||||
4. Update documentation when changing public APIs or adding new features
|
||||
|
||||
### Testing Requirements
|
||||
1. Run existing tests to ensure no regressions
|
||||
2. Add new tests for new functionality
|
||||
3. Ensure all tests pass before creating a PR
|
||||
|
||||
## Screenshot Requirements for UI Changes
|
||||
|
||||
**IMPORTANT**: When making changes that affect the user interface or visual output, you MUST capture screenshots to document the changes.
|
||||
|
||||
### When to Take Screenshots
|
||||
Take screenshots in the following scenarios:
|
||||
- Changes to web UI components, layouts, or styles
|
||||
- Modifications to console output or terminal displays
|
||||
- Updates to dashboards, admin panels, or user-facing interfaces
|
||||
- Changes that affect visual rendering or appearance
|
||||
- New UI features or components
|
||||
|
||||
### How to Take Screenshots Using Playwright
|
||||
|
||||
1. **Install Playwright** (if not already available):
|
||||
```bash
|
||||
npm install -D @playwright/test
|
||||
npx playwright install
|
||||
```
|
||||
|
||||
2. **Create a screenshot script** in `/tmp/take-screenshots.js`:
|
||||
```javascript
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
|
||||
// Navigate to the changed UI
|
||||
await page.goto('http://localhost:PORT/YOUR-PATH');
|
||||
|
||||
// Wait for the page to fully load
|
||||
await page.waitForLoadState('networkidle');
|
||||
|
||||
// Take screenshot
|
||||
await page.screenshot({
|
||||
path: 'screenshot-before.png',
|
||||
fullPage: true
|
||||
});
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
3. **Take "before" and "after" screenshots**:
|
||||
- Take a screenshot of the UI BEFORE your changes (if possible)
|
||||
- Make your code changes
|
||||
- Take a screenshot of the UI AFTER your changes
|
||||
- Save screenshots with descriptive names like:
|
||||
- `ui-change-before.png`
|
||||
- `ui-change-after.png`
|
||||
- `feature-name-screenshot.png`
|
||||
|
||||
4. **Alternative: Use Playwright Test**:
|
||||
```javascript
|
||||
const { test, expect } = require('@playwright/test');
|
||||
|
||||
test('capture UI changes', async ({ page }) => {
|
||||
await page.goto('http://localhost:PORT/YOUR-PATH');
|
||||
await expect(page).toHaveScreenshot('ui-state.png');
|
||||
});
|
||||
```
|
||||
|
||||
### Including Screenshots in PRs
|
||||
|
||||
1. **Save screenshots in a dedicated directory**:
|
||||
```bash
|
||||
mkdir -p /tmp/pr-screenshots
|
||||
mv *.png /tmp/pr-screenshots/
|
||||
```
|
||||
|
||||
2. **Upload screenshots to an image hosting service** (if needed):
|
||||
- Use GitHub's issue/PR comment attachment feature
|
||||
- Use temporary image hosting services for review purposes
|
||||
|
||||
3. **Include screenshots in PR description**:
|
||||
Add a "Screenshots" section to your PR description:
|
||||
```markdown
|
||||
## Screenshots
|
||||
|
||||
### Before
|
||||
|
||||
|
||||
### After
|
||||
|
||||
|
||||
### Description
|
||||
Brief description of what changed visually.
|
||||
```
|
||||
|
||||
4. **Add screenshots as PR comments**:
|
||||
If you can't edit the PR description directly, add screenshots as a comment:
|
||||
```markdown
|
||||
📸 **UI Changes Screenshot**
|
||||
|
||||
Here are screenshots showing the visual changes made in this PR:
|
||||
|
||||
**Before:**
|
||||
|
||||
|
||||
**After:**
|
||||
|
||||
```
|
||||
|
||||
### Screenshot Best Practices
|
||||
|
||||
1. **Capture the relevant area**: Focus on the changed UI elements, but include enough context
|
||||
2. **Use consistent viewport sizes**: Stick to common resolutions (e.g., 1920x1080, 1366x768)
|
||||
3. **Show multiple states** (if applicable):
|
||||
- Default state
|
||||
- Hover state
|
||||
- Active/clicked state
|
||||
- Error state
|
||||
- Loading state
|
||||
4. **Annotate if helpful**: Add arrows or highlights to draw attention to specific changes
|
||||
5. **Include mobile views**: For responsive changes, capture both desktop and mobile viewports
|
||||
|
||||
### Example Playwright Script for Common Scenarios
|
||||
|
||||
#### Capturing Multiple Views:
|
||||
```javascript
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
|
||||
// Desktop view
|
||||
await page.setViewportSize({ width: 1920, height: 1080 });
|
||||
await page.goto('http://localhost:3000/dashboard');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/dashboard-desktop.png', fullPage: true });
|
||||
|
||||
// Mobile view
|
||||
await page.setViewportSize({ width: 375, height: 667 });
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/dashboard-mobile.png', fullPage: true });
|
||||
|
||||
// Specific component
|
||||
const component = await page.locator('.my-changed-component');
|
||||
await component.screenshot({ path: '/tmp/pr-screenshots/component-detail.png' });
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
#### Capturing Interactive States:
|
||||
```javascript
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
await page.goto('http://localhost:3000/form');
|
||||
|
||||
// Default state
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/form-default.png' });
|
||||
|
||||
// Hover state
|
||||
await page.hover('button.submit');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/form-hover.png' });
|
||||
|
||||
// Filled state
|
||||
await page.fill('input[name="username"]', 'testuser');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/form-filled.png' });
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
1. Identify the issue or feature to implement
|
||||
2. Make code changes following best practices
|
||||
3. **If UI is affected**:
|
||||
- Set up local environment to run the application
|
||||
- Use Playwright to capture "before" and "after" screenshots
|
||||
- Save screenshots to `/tmp/pr-screenshots/`
|
||||
4. Run tests and ensure everything passes
|
||||
5. Create PR with detailed description
|
||||
6. **Include screenshots** in PR description or as a comment
|
||||
7. Address review feedback
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Playwright Documentation](https://playwright.dev/)
|
||||
- [Playwright Screenshots Guide](https://playwright.dev/docs/screenshots)
|
||||
- [Contributing Guidelines](../../CONTRIBUTING.md)
|
||||
- [Pull Request Template](../PULL_REQUEST_TEMPLATE.md)
|
||||
@@ -0,0 +1,226 @@
|
||||
# Screenshot Capture Quick Guide
|
||||
|
||||
## TL;DR
|
||||
When making UI changes, capture before/after screenshots using Playwright and include them in your PR.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install Playwright
|
||||
```bash
|
||||
npm install -D @playwright/test
|
||||
npx playwright install chromium
|
||||
```
|
||||
|
||||
### 2. Basic Screenshot Script
|
||||
Save as `/tmp/capture-ui.js`:
|
||||
```javascript
|
||||
const { chromium } = require('playwright');
|
||||
|
||||
(async () => {
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
|
||||
// Set viewport size
|
||||
await page.setViewportSize({ width: 1920, height: 1080 });
|
||||
|
||||
// Navigate to your changed page
|
||||
await page.goto('http://localhost:PORT/your-path');
|
||||
await page.waitForLoadState('networkidle');
|
||||
|
||||
// Take screenshot
|
||||
await page.screenshot({
|
||||
path: '/tmp/pr-screenshots/my-change.png',
|
||||
fullPage: true
|
||||
});
|
||||
|
||||
await browser.close();
|
||||
})();
|
||||
```
|
||||
|
||||
### 3. Run It
|
||||
```bash
|
||||
mkdir -p /tmp/pr-screenshots
|
||||
node /tmp/capture-ui.js
|
||||
```
|
||||
|
||||
## When to Screenshot
|
||||
|
||||
✅ **DO capture screenshots for:**
|
||||
- New UI components or pages
|
||||
- Layout changes
|
||||
- Style/theme modifications
|
||||
- Visual bug fixes
|
||||
- Responsive design changes
|
||||
- Dashboard or console updates
|
||||
|
||||
❌ **DON'T need screenshots for:**
|
||||
- Backend API changes
|
||||
- Database schema updates
|
||||
- Pure logic/algorithm changes
|
||||
- Non-visual bug fixes
|
||||
- Configuration changes
|
||||
|
||||
## Screenshot Checklist
|
||||
|
||||
- [ ] Capture "before" state (if possible)
|
||||
- [ ] Make your code changes
|
||||
- [ ] Capture "after" state
|
||||
- [ ] Use descriptive filenames
|
||||
- [ ] Include screenshots in PR description or comment
|
||||
- [ ] Capture both desktop and mobile views (if responsive)
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Compare Before/After
|
||||
```javascript
|
||||
// Before changes
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/before.png' });
|
||||
|
||||
// After changes (rebuild/reload your app)
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/after.png' });
|
||||
```
|
||||
|
||||
### Multiple Viewports
|
||||
```javascript
|
||||
const viewports = [
|
||||
{ name: 'desktop', width: 1920, height: 1080 },
|
||||
{ name: 'tablet', width: 768, height: 1024 },
|
||||
{ name: 'mobile', width: 375, height: 667 }
|
||||
];
|
||||
|
||||
for (const viewport of viewports) {
|
||||
await page.setViewportSize(viewport);
|
||||
await page.screenshot({
|
||||
path: `/tmp/pr-screenshots/${viewport.name}.png`
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Specific Component
|
||||
```javascript
|
||||
// Screenshot just the changed component
|
||||
const element = await page.locator('.my-component');
|
||||
await element.screenshot({
|
||||
path: '/tmp/pr-screenshots/component.png'
|
||||
});
|
||||
```
|
||||
|
||||
### Interactive States
|
||||
```javascript
|
||||
// Default
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/default.png' });
|
||||
|
||||
// Hover
|
||||
await page.hover('button.submit');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/hover.png' });
|
||||
|
||||
// Active/Focus
|
||||
await page.click('input[name="search"]');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/focus.png' });
|
||||
|
||||
// Error state
|
||||
await page.click('button.submit');
|
||||
await page.waitForSelector('.error-message');
|
||||
await page.screenshot({ path: '/tmp/pr-screenshots/error.png' });
|
||||
```
|
||||
|
||||
## Including in PR
|
||||
|
||||
### Option 1: Upload to PR Description
|
||||
```markdown
|
||||
## Screenshots
|
||||
|
||||
### Before
|
||||
|
||||
|
||||
### After
|
||||
|
||||
```
|
||||
|
||||
### Option 2: Add as Comment
|
||||
Drag and drop images into a PR comment or paste from clipboard.
|
||||
|
||||
### Option 3: Use GitHub CLI
|
||||
```bash
|
||||
gh pr comment PR_NUMBER --body "📸 Screenshots attached" -F /tmp/pr-screenshots/screenshot.png
|
||||
```
|
||||
|
||||
## Pro Tips
|
||||
|
||||
1. **Consistent sizing**: Use standard viewport sizes (1920x1080, 1366x768)
|
||||
2. **Full page**: Use `fullPage: true` to capture scrollable content
|
||||
3. **Wait for content**: Use `waitForLoadState('networkidle')` to ensure everything loads
|
||||
4. **Dark/Light mode**: Capture both themes if your change affects them
|
||||
5. **Annotations**: Use image editing tools to highlight specific changes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Browser not installed"
|
||||
```bash
|
||||
npx playwright install chromium
|
||||
```
|
||||
|
||||
### "Cannot connect to localhost"
|
||||
Make sure your dev server is running:
|
||||
```bash
|
||||
npm run dev # or your start command
|
||||
```
|
||||
|
||||
### "Page not loading"
|
||||
Add explicit waits:
|
||||
```javascript
|
||||
await page.waitForSelector('.main-content');
|
||||
await page.waitForTimeout(1000); // Last resort
|
||||
```
|
||||
|
||||
## Full Example
|
||||
|
||||
```javascript
|
||||
const { chromium } = require('playwright');
|
||||
const fs = require('fs');
|
||||
|
||||
(async () => {
|
||||
// Ensure screenshot directory exists
|
||||
const screenshotDir = '/tmp/pr-screenshots';
|
||||
if (!fs.existsSync(screenshotDir)) {
|
||||
fs.mkdirSync(screenshotDir, { recursive: true });
|
||||
}
|
||||
|
||||
const browser = await chromium.launch();
|
||||
const page = await browser.newPage();
|
||||
|
||||
// Test your changes on different pages
|
||||
const pages = [
|
||||
{ url: 'http://localhost:3000/dashboard', name: 'dashboard' },
|
||||
{ url: 'http://localhost:3000/settings', name: 'settings' }
|
||||
];
|
||||
|
||||
for (const pageInfo of pages) {
|
||||
console.log(`Capturing ${pageInfo.name}...`);
|
||||
|
||||
await page.goto(pageInfo.url);
|
||||
await page.waitForLoadState('networkidle');
|
||||
|
||||
// Desktop
|
||||
await page.setViewportSize({ width: 1920, height: 1080 });
|
||||
await page.screenshot({
|
||||
path: `${screenshotDir}/${pageInfo.name}-desktop.png`,
|
||||
fullPage: true
|
||||
});
|
||||
|
||||
// Mobile
|
||||
await page.setViewportSize({ width: 375, height: 667 });
|
||||
await page.screenshot({
|
||||
path: `${screenshotDir}/${pageInfo.name}-mobile.png`,
|
||||
fullPage: true
|
||||
});
|
||||
}
|
||||
|
||||
await browser.close();
|
||||
console.log('Screenshots saved to', screenshotDir);
|
||||
})();
|
||||
```
|
||||
|
||||
## More Information
|
||||
|
||||
For complete details, see [code-change-agent.md](./code-change-agent.md).
|
||||
@@ -75,4 +75,5 @@ You're a triage assistant for GitHub issues. Your task is to analyze issue #${{
|
||||
- If you have possible reproduction steps, include them in the comment
|
||||
- If you have any debugging strategies, include them in the comment
|
||||
- If appropriate break the issue down to sub-tasks and write a checklist of things to do.
|
||||
- **If the issue mentions UI/visual bugs or changes**, remind contributors to include screenshots in their PR using the guidance in `.github/agents/code-change-agent.md`
|
||||
- Use collapsed-by-default sections in the GitHub markdown to keep the comment tidy. Collapse all sections except the short main summary at the top.
|
||||
|
||||
Reference in New Issue
Block a user