from playwright.sync_api import Page, expect


def locate(page: Page, name, check_visible=True):
  """
  Locate an element or elements on the provided page by name.

  This function identifies elements on a web page using the locator API of the
  provided page object. The `name` parameter can either be a single locator
  string or a list of locator strings. If a list is provided, its elements are
  joined into a single comma-separated string before locating the elements.

  Args:
      page (Page): The web page object in which to locate the element(s).
      name (Union[str, List[str]]): Locator or list of locators to identify elements.
      check_visible(bool): Whether to check if the element is visible before returning it.

  Returns:
      Locator: The locator object for the given name.
  """
  if isinstance(name, list):
    name = ",".join(name)
  
  element = page.locator(name)
  
  if check_visible:
    expect(element).to_be_visible()
  
  return element


def fill(element, value):
  """
  Fills an element with a specified value and verifies that the element's value matches the provided value.

  Parameters:
  element : The UI element to be filled with the value.
  value : The value to fill into the element.

  Raises:
  AssertionError: If the element's value does not match the provided value after the fill operation.
  """
  element.fill(value)
  expect(element).to_have_value(value)


def debug(page: Page, checkpoint_name: str):
  """
  Takes a screenshot of the current state of a page and saves its full HTML content
  to support debugging at a specified checkpoint. The screenshot and HTML file are saved
  with checkpoint-specific filenames in the current working directory.

  This function is useful for capturing the visual state and content of the page at
  any moment during the script execution, helping in resolving issues or verifying
  state transitions.

  Arguments:
      page (Page): The page object whose state and content are to be captured.
      checkpoint_name (str): A descriptive name for the checkpoint. This is used to
          generate unique filenames for the screenshot and HTML file.
  """
  # Take screenshot
  page.screenshot(path=f"debug_{checkpoint_name}.png")
  
  # Save full HTML for inspection
  with open(f"debug_{checkpoint_name}.html", "w", encoding="utf-8") as f:
    f.write(page.content())
  
  with open(f"debug_{checkpoint_name}.txt", "w", encoding="utf-8") as f:
    f.writelines([
        f"Checkpoint: {checkpoint_name}\n",
        f"URL: {page.url}\n",
        f"Title: {page.title()}\n",
    ])


def check_not_in_content(page, keywords):
  """
  Checks that none of the specified keywords are present in the page content.

  This function iterates through a list of keywords and verifies that none of
  them are present in the given page's content. If any keyword is found, an
  AssertionError is raised with details about the number of times it was found.

  Args:
      page: A page object that provides access to retrieve text content.
      keywords: List of strings representing keywords to search in the page content.

  Raises:
      AssertionError: If any of the keywords are found in the page content.
  """
  for keyword in keywords:
    occurrences = page.get_by_text(keyword, exact=False)
    assert occurrences.count() == 0, f"Found {occurrences.count()} of '{keyword}' in page content which should not be visible"