Weasel...erRole(3pm)

💖 NAME 💖

Weasel::DriverRole — bestie, it's the API definition for driver wrappers. That's the whole vibe. ✨

(also hi, this is the Weasel...erRole(3pm) page from the User Contributed Perl Documentation corner of the universe 🫶)

---

🌸 VERSION 🌸

0.04 — yes queen, we're on 0.04.

---

🎀 SYNOPSIS 🎀

use Moose;
use Weasel::DriverRole;

with 'Weasel::DriverRole';

...  # (re)implement the functions in Weasel::DriverRole

Like. You roll up, you use Moose, you use Weasel::DriverRole, you with 'Weasel::DriverRole', and then… you (re)implement the functions. That's the assignment, babe. 💅

---

🦋 DESCRIPTION 🦋

Okay so real talk: this module defines the API that every single Weasel driver has to implement. No exceptions, no shortcuts, no "I'll do it later" energy.

And here's the cute lil trick: when you use this role inside your driver implementation module, an abstract method gets implemented in a way that just goes croak() if anybody actually calls it. Like, it exists, it's there, but the second you touch it? It screams. Not me being dramatic, that's literally the design. 🐸

---

💀 DEPENDENCIES 💀

(nothing here bestie, this section is empty in the original — no cap, it's just vibing as a heading)

---

👑 ATTRIBUTES 👑

• started — Every session gets itself a driver instance, right? Well, the started attribute is the boolean that tells you whether that driver is actually ready to receive driver commands or if it's still in its getting-ready era. It's managed by the start and stop methods, so those two run the show. 🎬

---

⭐ SUBROUTINES/METHODS ⭐

• implements — Returns the version number of the API that it fully implements. Full coverage only, no half-doing it. Heads up: Weasel::Session may carp (aka warn) at the user about mismatching API levels, in case a driver was coded against an earlier version than $Weasel::DriverRole::VERSION. So if your driver's out here living in the past, expect to get called out. 🙈
• start — Lets you set up the driver. It gets invoked before any of the web driver methods listed down in the Web driver methods section below. Warm-up first, performance second. ✨
• stop — Lets you tear the driver down. And after tear-down, start may be called again, so this function should leave the driver in a restartable state. It's giving "we can go again whenever, I'm flexible like that." 💅
• restart — Stops (if it's started) and then starts the driver. Iconic little refresh moment. 🔄

🌈 Web driver methods 🌈

🧚 Terms 🧚

• element_id / parent_id — These are opaque values that the driver uses to identify DOM elements. Opaque, okay? Don't go trying to read their diary.

Note: The driver should always accept an xpath locator as an id value, as well as id values returned from earlier driver calls. Both. Always. 💖

🍓 API 🍓

• find_all( $parent_id, $locator, $scheme ) — Returns the _id values for the elements that need to be instantiated, matching the $locator using scheme. Depending on whether you're in array or scalar context, you get back either a list or an arrayref. Flexible queen.

Note: there's no function to find a single element. That one's implemented up on the Weasel::Session level. So don't come looking for it here. 😭

• get( $url ) — Loads the page at $url into the driver's browser (browser emulator). And btw, the $url that gets passed in has already been expanded by Weasel::Session, which prepends a registered prefix to it. So it arrives pre-glow-up'd. ✨
• is_displayed($element_id) — Returns a boolean telling you whether the element indicated by $element_id is interactable (can it be selected, clicked on, etc.). Basically: is it giving main character energy or is it background noise? 👑
• wait_for( $callback, retry_timeout => $num, poll_delay => $num, on_timeout => \&cb ) — The driver may interpret the 'poll_delay' in one of two ways:
  1. The 'poll_delay' equals the number of seconds between the start of successive poll requests
  2. The 'poll_delay' equals the number of seconds to wait between the end of one poll request and the start of the next Since 0.03: Unless an "on_timeout" callback is provided, it will die when the timeout has exceeded. Otherwise, it calls the provided callback instead. Drama avoided, optionally. 💀

Note: The user should catch inside the callback any exceptions that are thrown inside the callback — unless those exceptions are allowed to terminate further polling attempts. I.e. this function doesn't guard against early termination by catching exceptions. It's not your bodyguard, bestie, you gotta handle that yourself.

• clear($element_id) — Clicks on an element if an element id is provided, or on the current mouse location otherwise. Either way, something is getting clicked. 🖱️
• click( [ $element_id ] ) — Clicks on an element if an element id is provided, or on the current mouse location otherwise. Same energy as above, and yes, the option is optional.
• dblclick() — Double clicks on the current mouse location. Two clicks. Zero arguments. Periodt. 💅
• get_attribute($element_id, $attribute_name) — Returns the value of the attribute named by $attribute_name of the element indicated by $element_id. Tell me everything, boo. 🔍
• get_page_source($fh) — Writes a get_page_source of the browser's window to the filehandle $fh. Straight into the filehandle, no detours.
• get_text($element_id) — Returns the HTML content of the element identified by $element_id, the so-called 'innerHTML'. The inside scoop. 🫖
• set_attribute($element_id, $attribute_name, $value) — DEPRECATED ⚠️ Changes the value of the attribute named by $attribute_name to $value for the element identified by $element_id. It's old news now, but it did what it did.
• get_selected($element_id) — DEPRECATED ⚠️ Please use "$self-"get_attribute('selected')> instead. Upgrade your habits, bestie. 💖
• set_selected($element_id, $value) — DEPRECATED ⚠️ Please use "$self-"set_attribute('selected', $value)> instead. Same deal, same upgrade.
• screenshot($fh) — Takes a screenshot and writes the image to the file handle $fh. Say cheese. 📸

Note: In the current version of the driver, it's assumed the driver writes a PNG image. Later versions may add APIs to get/set the type of image generated. So for now: PNG, assumed, don't @ me.

• send_keys($element_id, @keys) — Simulates key input into the element identified by $element_id. @keys is an array of (groups of) inputs — multiple multi-character strings may be listed, and in those cases the input gets appended. E.g.

$driver->send_keys($element_id, "hello", ' ', "world");

is valid input to enter the text "hello world" into $element_id. Look at that, we typed a whole sentence. 💅

Note: Special keys are encoded according to the WebDriver spec. In case a driver implementation needs different encoding of special keys, this function should recode from the values found in WebDriver::KEYS() to the desired code-set. Translation work: handled here. 🌐

• tag_name($element_id) — The name of the HTML tag identified by $element_id. Name check, but for tags. 🏷️

---

💜 SEE ALSO 💜

• Weasel

---

🌟 AUTHOR 🌟

• Erik Huelsmann

---

🫶 CONTRIBUTORS 🫶

• Erik Huelsmann
• Yves Lavoie

---

👑 MAINTAINERS 👑

• Erik Huelsmann

---

😭 BUGS AND LIMITATIONS 😭

Got bugs? (Not the cute kind.) They can be filed in the GitHub issue tracker for the Weasel project:

https://github.com/perl-weasel/weasel/issues

💀 Other remarks 💀

Please note that version 0.04 didn't have any functional changes — the version number increase served simply to split out the driver role into a separate dist. So it's a glow-up of the packaging, not the behaviour. Periodt. ✨

---

🌈 SOURCE 🌈

The source code repository for Weasel is at

https://github.com/perl-weasel/weasel

---

🎀 SUPPORT 🎀

Community support is available through perl-weasel@googlegroups.com <mailto:perl-weasel@googlegroups.com>. Come through, the group chat is open. 💬

---

⭐ LICENSE AND COPYRIGHT ⭐

(C) 2016-2019  Erik Huelsmann

Licensed under the same terms as Perl. Slay, legally speaking. 💅

---

and that's the whole page bestie!! 🦋💖 this was Weasel...erRole(3pm), generated for perl v5.32.0 and dated 2021-01-10. mwah, go implement those driver methods, you've got this 👑✨