Metadata-Version: 2.5
Name: pomcorn
Version: 0.11.0
Summary: Base implementation of Page Object Model
Project-URL: Homepage, https://pypi.org/project/pomcorn/
Project-URL: Repository, https://github.com/saritasa-nest/pomcorn/
Project-URL: Documentation, https://saritasa-nest.github.io/pomcorn/latest/
Project-URL: Changelog, https://saritasa-nest.github.io/pomcorn/latest/changelog/
Project-URL: Releases, https://github.com/saritasa-nest/pomcorn/releases/
Project-URL: Bug Tracker, https://github.com/saritasa-nest/pomcorn/issues/
Project-URL: Contributing, https://saritasa-nest.github.io/pomcorn/latest/contributing/
Author-email: Saritasa <pypi@saritasa.com>
Maintainer-email: Roman Gorbil <roman.gorbil@saritasa.com>, Ruslan Ivanov <ruslan.ivanov@saritasa.com>
License-Expression: MIT
License-File: LICENSE
Keywords: autotests,browser,page object,page object model,page object pattern,parsing,pom,python,selenium,webdriver
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Requires-Dist: selenium>=4.12
Description-Content-Type: text/markdown

# Pomcorn

![GitHub last commit](https://img.shields.io/github/last-commit/saritasa-nest/pomcorn)
![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/saritasa-nest/pomcorn/run_pre_commit.yaml)
![PyPI](https://img.shields.io/pypi/v/pomcorn)
![PyPI - Status](https://img.shields.io/pypi/status/pomcorn)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pomcorn)
![PyPI - License](https://img.shields.io/pypi/l/pomcorn)
![PyPI - Downloads](https://img.shields.io/pypi/dm/pomcorn)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/j178/prek)

Check out our other open-source [projects](https://github.com/orgs/saritasa-nest/repositories?q=visibility%3Apublic+archived%3Afalse+fork%3Afalse+language%3APython)

**Pomcorn**, or **Page Object Model corn**, is a Python package that contains base classes to create systems based on
[Selenium](https://github.com/SeleniumHQ/selenium#selenium) framework and **Page Object Model** pattern.
You can [read more about this pattern](https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/).
The package can be used to create autotesting systems, parsing scripts and anything that requires interaction with the browser.

The package includes next base classes to create Page Object Model (``POM``) pages:

```mermaid
  classDiagram
    WebView <|-- Component
    WebView <|-- Page
    Component <|-- ListComponent
    Component .. Locator
    Page .. Component

    class WebView{
        -webdriver: Webdriver
    }
    class Page{
        +wait_until_loaded()
        +open()
    }
    class Component{
        -page: Page
        -base_locator: Locator
        + wait_until_visible()
    }
    class ListComponent{
        -item_locator: Locator
        +count()
        +all()
        +get_item_by_text()
    }
    class Locator{
      -query: String
    }

```

It also includes [classes to locate elements](https://saritasa-nest.github.io/pomcorn/latest/locators/)
on the web page and a number of additional [waiting conditions](https://saritasa-nest.github.io/pomcorn/latest/waits_conditions/).

## Installation

You can install it by **pip**:

```bash
  pip install pomcorn
```

Or **poetry**:

```bash
  poetry add pomcorn
```

## Documentation

Link to the documentation: [https://saritasa-nest.github.io/pomcorn/latest/](https://saritasa-nest.github.io/pomcorn/latest/).

## Usage

Install pomcorn using [installation guide](https://saritasa-nest.github.io/pomcorn/latest/installation/).

Below is the code that opens ``PyPI.org``, searches for packages by name and prints names of
found packages to the terminal. The script contains all base classes contained
in ``pomcorn``: **Page**, **Component**, **ListComponent** and **Element**.

```python
from typing import Self

from selenium.webdriver import Chrome
from selenium.webdriver.common.keys import Keys
from selenium.webdriver.remote.webdriver import WebDriver

from pomcorn import Component, Element, ListComponent, Page, locators


# Prepare base page
class PyPIPage(Page):
    APP_ROOT = "https://pypi.org"

    search = Element(locators.IdLocator("search"))

    def check_page_is_loaded(self) -> bool:
        return self.init_element(locators.TagNameLocator("main")).is_displayed


# Prepare components
Package = Component[PyPIPage]


class PackageList(ListComponent[Package, PyPIPage]):
    relative_item_locator = locators.ClassLocator("snippet__name")

    @property
    def names(self) -> list[str]:
        return [package.body.get_text() for package in self.all]


# Prepare search page
class SearchPage(PyPIPage):
    @classmethod
    def open(cls, webdriver: WebDriver, **kwargs) -> Self:
        pypi_page = super().open(webdriver, **kwargs)
        # Specific logic for PyPI for an open search page
        pypi_page.search.fill("")
        pypi_page.search.send_keys(Keys.ENTER)
        return cls(webdriver, **kwargs)

    @property
    def results(self) -> PackageList:
        return PackageList(
            page=self,
            base_locator=locators.PropertyLocator(
                prop="aria-label",
                value="Search results",
            ),
        )

    def find(self, query: str) -> PackageList:
        self.search.fill(query)
        self.search.send_keys(Keys.ENTER)
        return self.results


search_page = SearchPage.open(webdriver=Chrome())
print(search_page.find("saritasa").names)
search_page.webdriver.close()
```

For more information about package classes, you can read in [Object Hierarchy](https://saritasa-nest.github.io/pomcorn/latest/objects_hierarchy/)
and [Developer Interface](https://saritasa-nest.github.io/pomcorn/latest/developer_interface/).

Also you can try our [demo autotests project](https://saritasa-nest.github.io/pomcorn/latest/demo/).
