BIPAuto/CLAUDE.md

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.

# 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():

url = f"{os.getenv('ERP_URL').rstrip('/')}/yonbip/resources/uap/rbac/login/main/index.html"

Common Commands

# 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.