8d59fc6ef8
- Fix return value from 2-tuple to 4-tuple (browser, context, page, main_frame) - Correct function signature to match actual implementation - Documentation now matches the actual API Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
BIPAuto is a Python automation framework for interacting with Yonyou BIP (用友BIP) enterprise resource planning systems. The project uses Playwright for browser automation to perform login, logout, and other operations on the web-based ERP system.
|
|
|
|
## Development Environment
|
|
|
|
**Virtual Environment**: All Python scripts must be executed within the local `.venv` virtual environment.
|
|
|
|
```bash
|
|
# Create virtual environment (if not exists)
|
|
python -m venv .venv
|
|
|
|
# Activate (Windows Git Bash)
|
|
source .venv/Scripts/activate
|
|
|
|
# Install/update dependencies
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Environment Configuration
|
|
|
|
The project relies heavily on environment variables loaded from `.env` file in the project root. Never commit `.env` to version control - use `.env.example` as a template.
|
|
|
|
**Critical Environment Variables:**
|
|
- `PLAYWRIGHT_BROWSERS_PATH` - Path to Playwright browser installation (custom path, not default)
|
|
- `ERP_URL` - Base URL for the ERP system
|
|
- `ERP_USERNAME` - Login username
|
|
- `ERP_PASSWORD` - Login password
|
|
- `ERP_HEADLESS` - Whether to run browser in headless mode (true/false)
|
|
- `ERP_IGNORE_HTTPS_ERRORS` - Whether to ignore HTTPS certificate errors (true/false)
|
|
|
|
Note: Test scripts are responsible for loading environment variables and passing configuration to utility functions.
|
|
|
|
## Architecture
|
|
|
|
### Module Structure
|
|
|
|
**`utils/auth.py`** - Core authentication module (pure functions)
|
|
- `login(playwright, username, password, url, headless, ignore_https_errors, verbose=True)` - Handles Yonyou BIP login with automatic force-login popup detection. Requires all parameters (playwright, username, password, url, headless, ignore_https_errors).
|
|
- `logout(page)` - Performs logout with confirmation dialog handling.
|
|
- Returns tuple: `(browser, context, page, main_frame)` where `main_frame` is the forwardFrame iframe.
|
|
- Callers are responsible for browser lifecycle management (context.close(), browser.close()).
|
|
|
|
**`tests/`** - Test suite
|
|
- All test files must add `PROJECT_ROOT` to `sys.path` to import `utils` modules
|
|
- Tests follow pattern: load dotenv, set browser path environment variable, run Playwright operations
|
|
- All output and log messages use English only (Chinese text reserved for page element selectors)
|
|
|
|
### Page Interaction Pattern
|
|
|
|
Yonyou BIP uses a nested iframe structure:
|
|
1. Main page contains `#forwardFrame` iframe
|
|
2. All form elements (username, password, buttons) are located within this iframe
|
|
3. Use `page.locator("#forwardFrame").content_frame` to access the iframe
|
|
4. Element selectors use role-based locators with Chinese names matching the UI:
|
|
- `get_by_role("textbox", name="用户名")` for username field
|
|
- `get_by_role("button", name="登录")` for login button
|
|
|
|
### Force Login Handling
|
|
|
|
The system automatically detects and handles a force-login confirmation dialog that appears after clicking the login button. The code checks for a "确定" (Confirm) button and clicks it if present.
|
|
|
|
### URL Construction Pattern
|
|
|
|
Callers must construct the complete login URL before passing to `login()`:
|
|
|
|
```python
|
|
url = f"{os.getenv('ERP_URL').rstrip('/')}/yonbip/resources/uap/rbac/login/main/index.html"
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Run authentication configuration test
|
|
python tests/test_auth_config.py
|
|
|
|
# Run login/logout test
|
|
python tests/test_login.py
|
|
|
|
# Run any test with virtual environment
|
|
source .venv/Scripts/activate && python tests/<test_file>.py
|
|
```
|
|
|
|
## Code Conventions
|
|
|
|
1. **English Only**: All user-facing output, docstrings, comments, and log messages must be in English. Chinese text is only used for Playwright element selectors matching the actual UI.
|
|
|
|
2. **Environment-First**: Test scripts load environment variables and explicitly pass configuration to utility functions. No hardcoded values in code.
|
|
|
|
3. **Error Handling**: Functions that depend on environment variables should raise clear `ValueError` exceptions when required variables are missing.
|
|
|
|
4. **Path Handling**: Use `pathlib.Path` for all file system operations. Project root is determined as `Path(__file__).resolve().parent.parent` from within `utils/` modules.
|
|
|
|
5. **Test Coverage**: **ALL new components MUST include corresponding unit tests.** When creating new functionality in `utils/` or any other module, you must simultaneously create a test file in `tests/` directory that validates the component's behavior. Tests should verify both success and failure scenarios.
|