Skip to content

Commit 118c609

Browse files
Copilotcodeskyblue
Copilot
and
codeskyblue
authored
Add comprehensive GitHub Copilot instructions for adbutils development (#190)
* Initial plan * Create comprehensive GitHub Copilot instructions for adbutils Co-authored-by: codeskyblue <3281689+codeskyblue@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: codeskyblue <3281689+codeskyblue@users.noreply.github.com>
1 parent 250839e commit 118c609

1 file changed

Lines changed: 159 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# adbutils - Python ADB Library
2+
3+
adbutils is a pure Python library for Android Debug Bridge (ADB) operations. It provides both a Python API and command-line interface for device management, shell commands, file transfer, and Android app operations.
4+
5+
**ALWAYS reference these instructions first and follow them precisely. Only fallback to additional search and context gathering if the information in these instructions is incomplete or found to be in error.**
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Install
10+
- Install system dependencies:
11+
- `sudo apt update && sudo apt install -y android-tools-adb` -- installs ADB tool (takes 2-3 minutes)
12+
- `python --version` -- ensure Python 3.8+ is available
13+
- Install adbutils in development mode:
14+
- `pip install -e .` -- takes ~2 seconds. Install local package in editable mode.
15+
- `pip install pytest pytest-cov` -- install test dependencies (~30 seconds)
16+
- Verify installation:
17+
- `python -c "import adbutils; print('Import successful')"` -- basic import test
18+
- `python -m adbutils --help` -- verify CLI works
19+
- `python -m adbutils -V` -- check ADB server version (starts daemon if needed)
20+
21+
### Build and Test
22+
- **Unit Tests (FAST)**: `pytest tests/` -- 16 tests, takes ~2 seconds. ALWAYS run these.
23+
- **E2E Tests (SLOW/RISKY)**: `pytest e2etests/` -- 46 tests, requires Android devices, can hang indefinitely.
24+
- **NEVER CANCEL** - timeout after 10+ minutes if no devices available
25+
- **WARNING**: These tests can hang without devices connected - use Ctrl+C if needed
26+
- **RECOMMENDATION**: Skip E2E tests during development unless testing device-specific features
27+
- **Coverage**: `pytest --cov=. --cov-report xml --cov-report term` -- run tests with coverage
28+
- **Import Test**: `python -c "import adbutils; adb = adbutils.AdbClient(); print('Success')"` -- verify basic functionality
29+
30+
### Development Workflow
31+
- ALWAYS run unit tests after making changes: `pytest tests/`
32+
- NEVER run E2E tests unless you have Android devices connected
33+
- Test CLI functionality: `python -m adbutils --dump-info` -- shows ADB info and connected devices
34+
- Validate import and basic operations work after code changes
35+
36+
## Validation
37+
38+
### Essential Validation Steps
39+
- ALWAYS run unit tests before committing: `pytest tests/` (takes ~2 seconds)
40+
- Test basic import: `python -c "import adbutils; print('OK')"`
41+
- Test CLI: `python -m adbutils --help` and `python -m adbutils -V`
42+
- Check ADB connection: `python -m adbutils --dump-info` -- shows ADB path and server version
43+
44+
### Manual Testing Scenarios
45+
After making changes, validate these core scenarios:
46+
- **Basic ADB Operations**:
47+
- `python -c "import adbutils; adb = adbutils.AdbClient(); print('Server version:', adb.server_version())"`
48+
- **CLI Interface**:
49+
- `python -m adbutils -V` -- check server version
50+
- `python -m adbutils -l` -- list devices (empty if none connected)
51+
- `python -m adbutils --dump-info` -- show comprehensive ADB info
52+
- **Library Import**: Ensure all modules import without errors
53+
54+
### What NOT to Test
55+
- DO NOT run `pytest e2etests/` without Android devices - tests will hang
56+
- DO NOT test device-specific functionality without actual devices connected
57+
- DO NOT test APK installation features without APK files and devices
58+
59+
## Common Tasks
60+
61+
### Repository Structure
62+
```
63+
adbutils/ # Main package directory
64+
├── __init__.py # Main API exports
65+
├── _adb.py # Core ADB client implementation
66+
├── _device.py # Device operations
67+
├── _device_base.py # Base device functionality
68+
├── shell.py # Shell command handling
69+
├── sync.py # File transfer operations
70+
├── install.py # APK installation
71+
├── errors.py # Exception definitions
72+
└── binaries/ # Binary dependencies
73+
74+
tests/ # Unit tests (FAST - always run)
75+
├── test_adb_server.py # ADB server tests
76+
├── test_adb_shell.py # Shell command tests
77+
├── test_devices.py # Device listing tests
78+
└── test_forward.py # Port forwarding tests
79+
80+
e2etests/ # End-to-end tests (SLOW - device required)
81+
├── test_adb.py # Full ADB integration tests
82+
├── test_device_*.py # Device operation tests
83+
└── conftest.py # Test configuration
84+
85+
examples/ # Usage examples
86+
└── reset-offline.py # Example script
87+
88+
docs/ # Documentation
89+
└── PROTOCOL.md # ADB protocol documentation
90+
```
91+
92+
### Key Configuration Files
93+
- `setup.py` -- Package setup with pbr integration
94+
- `setup.cfg` -- Package metadata and build configuration
95+
- `requirements.txt` -- Runtime dependencies
96+
- `pytest.ini` -- Test configuration
97+
- `.github/workflows/main.yml` -- CI/CD pipeline
98+
99+
### Dependencies and Versions
100+
- **Python**: 3.8+ required (tested with 3.8 and 3.12)
101+
- **System**: ADB tool must be installed (`android-tools-adb` package)
102+
- **Runtime**: requests, deprecation, retry2, Pillow
103+
- **Optional**: apkutils (for APK parsing, install with `pip install adbutils[all]`)
104+
- **Development**: pytest, pytest-cov
105+
106+
### Build Information
107+
- **No complex build process** - this is a pure Python package
108+
- Uses setuptools with pbr (Python Build Reasonableness)
109+
- Package installation via `pip install -e .` takes ~2 seconds
110+
- No compilation steps, native dependencies, or external build tools required
111+
112+
### Environment Variables
113+
The following environment variables affect adbutils behavior:
114+
- `ADBUTILS_ADB_PATH` -- specify custom adb binary path
115+
- `ANDROID_SERIAL` -- default device serial for operations
116+
- `ANDROID_ADB_SERVER_HOST` -- ADB server host (default: 127.0.0.1)
117+
- `ANDROID_ADB_SERVER_PORT` -- ADB server port (default: 5037)
118+
119+
### Timing Expectations and Timeouts
120+
- **Package install**: `pip install -e .` takes ~2 seconds
121+
- **Unit tests**: `pytest tests/` takes ~2 seconds for 16 tests
122+
- **E2E tests**: `pytest e2etests/` - **CRITICAL: NEVER CANCEL** - can take 10+ minutes or hang indefinitely without devices
123+
- **Basic imports**: `python -c "import adbutils"` takes ~0.1 seconds
124+
- **CLI commands**: Most CLI operations take <1 second
125+
- **ADB daemon start**: First ADB command may take 1-2 seconds to start daemon
126+
127+
### CLI Reference
128+
Common commands for testing and validation:
129+
```bash
130+
# Basic info and status
131+
python -m adbutils --help # Show all available commands
132+
python -m adbutils -V # Show ADB server version
133+
python -m adbutils -l # List connected devices
134+
python -m adbutils --dump-info # Show comprehensive ADB information
135+
136+
# Device operations (require connected devices)
137+
python -m adbutils --list-packages # List installed packages
138+
python -m adbutils --screenshot screen.jpg # Take screenshot
139+
python -m adbutils --shell # Open interactive shell
140+
141+
# File operations (require connected devices)
142+
python -m adbutils --push local.txt:/sdcard/remote.txt
143+
python -m adbutils --pull /sdcard/remote.txt
144+
```
145+
146+
### Troubleshooting
147+
- **"daemon not running"**: Normal - ADB daemon starts automatically on first command
148+
- **Import errors**: Run `pip install -e .` to reinstall in development mode
149+
- **E2E test hangs**: Expected without devices - use Ctrl+C and run unit tests instead
150+
- **Permission denied**: Use `sudo` for ADB installation commands
151+
- **No devices found**: Normal in CI environments - focus on unit tests and basic CLI validation
152+
153+
### Development Best Practices
154+
- ALWAYS run `pytest tests/` before committing changes
155+
- Use the unit tests as the primary validation method - they are fast and reliable
156+
- Test basic import and CLI functionality after significant changes
157+
- Check the GitHub Actions workflow (`.github/workflows/main.yml`) for CI requirements
158+
- Focus on the core library code in `adbutils/` directory for most modifications
159+
- Use `python -m adbutils --dump-info` to verify ADB connectivity and basic functionality

0 commit comments

Comments
 (0)