Metadata-Version: 2.4
Name: medicentrev3_auth
Version: 1.0.1
Summary: Authentication and navigation module for MedicentreV3 automation
Author-email: Denis Ndiritu <denis@hanmak.co.ke>
License: MIT
Project-URL: Homepage, https://github.com/Hanmak-Technologies-Automation-Project/medicentrev3-authentication-package
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: selenium>=4.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: webdriver-manager>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"

# MedicentreV3 Auth

`medicentrev3_auth` is a reusable Python package for automating MedicentreV3 login, browser session setup, navigation, screenshots, and logout flows.

It is built for MedicentreV3 automation scripts that need a consistent way to authenticate, select a facility branch, open modules such as Procurement, Inventory, Accounts, Configuration, Security, and Human Resource, then continue with module-specific Selenium work.

## Features

- Handles the MedicentreV3 login flow: facility access code, branch selection, username, and password.
- Creates and configures a Chrome Selenium WebDriver session.
- Uses `webdriver-manager` to install and manage ChromeDriver automatically.
- Loads credentials and settings from environment variables or a `.env` file.
- Provides reusable navigation helpers for common MedicentreV3 modules and panels.
- Saves screenshots during login, navigation, and error flows.
- Supports headless and visible browser sessions.
- Cleans up browser sessions with `logout()` and `quit_driver()`.
- Includes convenience helpers for quick session creation.

## Installation

Install the published package:

```bash
pip install medicentrev3_auth
```

If you are installing into a project, it is best to use a virtual environment first:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install medicentrev3_auth
```

On macOS or Linux, activate the environment with:

```bash
source .venv/bin/activate
```

## Upgrade

Upgrade to the latest published version:

```bash
pip install --upgrade medicentrev3_auth
```

If your environment appears to be using a cached or stale version, force a reinstall:

```bash
pip install --force-reinstall --upgrade medicentrev3_auth
```

## Requirements

The package installs these runtime dependencies automatically:

- `selenium>=4.0.0`
- `python-dotenv>=0.19.0`
- `webdriver-manager>=3.8.0`

You also need Google Chrome installed on the machine running the automation.

## Configuration

Create a `.env` file in the project where your automation script runs:

```env
MEDICENTRE_BASE_URL=https://medicentrev3.hanmak.co.ke
MEDICENTRE_ACCESS_CODE=your_facility_access_code
MEDICENTRE_BRANCH=your_branch_name
MEDICENTRE_USERNAME=your_username
MEDICENTRE_PASSWORD=your_password
```

`MEDICENTRE_BASE_URL` is optional. If omitted, it defaults to:

```env
https://medicentrev3.hanmak.co.ke
```

The access code, branch, username, and password are required. The package raises a `ValueError` during initialization if any required value is missing.

## Basic Usage

```python
from medicentrev3_auth import MedicentreAuth

auth = MedicentreAuth(headless=False)

try:
    if auth.setup_and_login():
        auth.navigate_to("procurement", "suppliers")

        # Continue with your module-specific Selenium automation.
        driver = auth.driver
        print(driver.title)
finally:
    auth.logout()
    auth.quit_driver()
```

## Context Manager Usage

Use the class as a context manager when you want logout and browser shutdown to happen automatically:

```python
from medicentrev3_auth import MedicentreAuth

with MedicentreAuth(headless=True) as auth:
    if auth.setup_and_login():
        auth.navigate_to("accounts", "ledger_accounts")
        # Continue automation here.
```

## Quick Login Helper

`quick_login()` creates an auth session, sets up the browser, logs in, and returns the logged-in session. It returns `None` if login fails.

```python
from medicentrev3_auth import quick_login

auth = quick_login(headless=False)

if auth:
    try:
        auth.navigate_to("inventory", "unit_of_measure")
    finally:
        auth.logout()
        auth.quit_driver()
```

## Create Session Helper

Use `create_auth_session()` when you want a configured `MedicentreAuth` object but still want to control setup and login manually:

```python
from medicentrev3_auth import create_auth_session

auth = create_auth_session(headless=True, base_dir="automation_output")

if auth.setup_and_login():
    auth.navigate_to("configuration", "rooms")
```

## Navigation

Navigate to a main module:

```python
auth.navigate_to("procurement")
```

Navigate to a module panel:

```python
auth.navigate_to("procurement", "purchase_orders")
auth.navigate_to("inventory", "unit_of_measure")
auth.navigate_to("accounts", "payment_modes")
auth.navigate_to("security", "system_users")
auth.navigate_to("configuration", "departments")
```

Common module aliases are supported:

| Alias | Module |
| --- | --- |
| `proc` | `procurement` |
| `inv` | `inventory` |
| `acc` | `accounts` |
| `hr` | `human_resource` |
| `sec` | `security` |
| `config` | `configuration` |

Common panel aliases are also supported:

| Alias | Panel |
| --- | --- |
| `supp` | `suppliers` |
| `bills` | `supplier_bills` |
| `prn` | `purchase_requisition_note` |
| `po` | `purchase_orders` |
| `grn` | `goods_received_notes` |
| `ap` | `ap_payment_vouchers` |
| `uom` | `unit_of_measure` |
| `ledger` | `ledger_accounts` |
| `roles` | `user_roles` |
| `sysusers` | `system_users` |
| `dept` | `departments` |
| `storage` | `storage_locations` |

Example with aliases:

```python
auth.navigate_to("proc", "po")
auth.navigate_to("config", "dept")
```

## Screenshots and Output Folders

The package creates these folders under `base_dir`:

- `logs`
- `auth_logs`
- `screenshots`

By default, `base_dir` is the current working directory. You can change it:

```python
auth = MedicentreAuth(base_dir="automation_output")
```

Screenshots are saved during login, after login, navigation, and error handling.

## Custom Elements

You can add locators for project-specific automation after login:

```python
from selenium.webdriver.common.by import By

auth.add_element("custom_button", (By.ID, "btnCustom"))
auth.click_element(auth.elements["custom_button"])
```

Useful helper methods include:

- `find_element(locator, timeout=10)`
- `find_elements(locator, timeout=10)`
- `wait_for_element(locator, timeout=30)`
- `click_element(locator)`
- `navigate_to_url(url)`
- `get_current_url()`
- `get_page_title()`
- `save_screenshot(name, subdirectory="auth")`

## Development Installation

For local development from this repository:

```bash
git clone https://github.com/Hanmak-Technologies-Automation-Project/medicentrev3-authentication-package.git
cd medicentrev3-authentication-package
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
```

On macOS or Linux:

```bash
source .venv/bin/activate
pip install -e ".[dev]"
```

## Troubleshooting

If ChromeDriver setup fails, make sure Google Chrome is installed and reachable from your environment.

If login fails immediately, check that all required environment variables are present and that the `.env` file is in the directory where your script is running.

If navigation fails, verify that the logged-in user has permission to access the target module or panel.

If an updated package version does not seem to load, run:

```bash
pip show medicentrev3_auth
pip install --force-reinstall --upgrade medicentrev3_auth
```

## Import Path

Install with:

```bash
pip install medicentrev3_auth
```

Import with:

```python
from medicentrev3_auth import MedicentreAuth, create_auth_session, quick_login
```

## License

This package is published under the MIT License.
