Module: Unmagic::Browser::Console::Helpers

Defined in:
lib/unmagic/browser/console/helpers.rb

Overview

The verbs, as bare words.

A console is the one place where open "https://example.com" beats session = browser.open("https://example.com") — you're typing, not writing code that has to survive. Every verb here drives one current session, opened by #open and remembered until you #close it, so the reads and the actions all know what page they're on without being told.

The four verbs that work on a whole page — #markdown, #html, #screenshot and #pdf — take an optional URL. With one they're a one-off grab that opens nothing; without one they read the current session.

start mixes this into a console's main. Mix it in yourself to get the same verbs somewhere else.

Instance Method Summary collapse

Instance Method Details

#all(query = nil, **options) ⇒ Array<Unmagic::Browser::Element>

Parameters:

Returns:



277
278
279
 
# File 'lib/unmagic/browser/console/helpers.rb', line 277

def all(query = nil, **options)
  current.all(query, **options)
end

#attach_file(query = nil, *paths, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the file field's label or name

  • paths (Array<String>) —

    the files to attach

  • options (Hash) —

    see Locator.build

Returns:



153
154
155
 
# File 'lib/unmagic/browser/console/helpers.rb', line 153

def attach_file(query = nil, *paths, **options)
  current.attach_file(query, *paths, **options)
end

#back ⇒ Unmagic::Browser::Session

Returns:



70
71
72
 
# File 'lib/unmagic/browser/console/helpers.rb', line 70

def back
  current.go_back
end

#browser ⇒ Unmagic::Browser

Returns the browser the verbs run against.

Returns:



25
26
27
 
# File 'lib/unmagic/browser/console/helpers.rb', line 25

def browser
  Console.browser
end

#check(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the checkbox's label or name

  • options (Hash) —

    see Locator.build

Returns:



131
132
133
 
# File 'lib/unmagic/browser/console/helpers.rb', line 131

def check(query = nil, **options)
  current.check(query, **options)
end

#choose(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the radio button's label or name

  • options (Hash) —

    see Locator.build

Returns:



145
146
147
 
# File 'lib/unmagic/browser/console/helpers.rb', line 145

def choose(query = nil, **options)
  current.choose(query, **options)
end

#click(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

Returns:



102
103
104
 
# File 'lib/unmagic/browser/console/helpers.rb', line 102

def click(query = nil, **options)
  current.click(query, **options)
end

#click_button(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the button's text, value or name

  • options (Hash) —

    see Locator.build

Returns:



109
110
111
 
# File 'lib/unmagic/browser/console/helpers.rb', line 109

def click_button(query = nil, **options)
  current.click_button(query, **options)
end

#click_link(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the link's text

  • options (Hash) —

    see Locator.build

Returns:



116
117
118
 
# File 'lib/unmagic/browser/console/helpers.rb', line 116

def click_link(query = nil, **options)
  current.click_link(query, **options)
end

#close ⇒ nil

Returns:

  • (nil) 


301
302
303
304
 
# File 'lib/unmagic/browser/console/helpers.rb', line 301

def close
  Console.session&.close
  Console.session = nil
end

#emulate(config = nil, **knobs) ⇒ Unmagic::Browser::Emulation

Returns what's being emulated now.

Parameters:

  • config (Unmagic::Browser::Emulation, Hash, nil) (defaults to: nil) —

    a whole configuration

  • knobs (Hash) —

    individual settings, layered over what's already emulated

Returns:



296
297
298
 
# File 'lib/unmagic/browser/console/helpers.rb', line 296

def emulate(config = nil, **knobs)
  current.emulate(config, **knobs)
end

#fill_in(query = nil, with:, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the field's label, placeholder, name or id

  • with (String) —

    what to type

  • options (Hash) —

    see Locator.build

Returns:



95
96
97
 
# File 'lib/unmagic/browser/console/helpers.rb', line 95

def fill_in(query = nil, with:, **options)
  current.fill_in(query, with: with, **options)
end

#find(query = nil, **options) ⇒ Unmagic::Browser::Element

Parameters:

Returns:



270
271
272
 
# File 'lib/unmagic/browser/console/helpers.rb', line 270

def find(query = nil, **options)
  current.find(query, **options)
end

#forward ⇒ Unmagic::Browser::Session

Returns:



75
76
77
 
# File 'lib/unmagic/browser/console/helpers.rb', line 75

def forward
  current.go_forward
end

#has_button?(query = nil, **options) ⇒ Boolean

Returns whether such a button is on the page right now.

Parameters:

Returns:

  • (Boolean) —

    whether such a button is on the page right now



241
242
243
 
# File 'lib/unmagic/browser/console/helpers.rb', line 241

def has_button?(query = nil, **options)
  current.has_button?(query, **options)
end

#has_field?(query = nil, **options) ⇒ Boolean

Returns whether such a field is on the page right now.

Parameters:

Returns:

  • (Boolean) —

    whether such a field is on the page right now



255
256
257
 
# File 'lib/unmagic/browser/console/helpers.rb', line 255

def has_field?(query = nil, **options)
  current.has_field?(query, **options)
end

#has_link?(query = nil, **options) ⇒ Boolean

Returns whether such a link is on the page right now.

Parameters:

Returns:

  • (Boolean) —

    whether such a link is on the page right now



248
249
250
 
# File 'lib/unmagic/browser/console/helpers.rb', line 248

def has_link?(query = nil, **options)
  current.has_link?(query, **options)
end

#has_selector?(css) ⇒ Boolean

Returns whether anything matches it right now.

Parameters:

  • css (String) —

    a CSS selector

Returns:

  • (Boolean) —

    whether anything matches it right now



261
262
263
 
# File 'lib/unmagic/browser/console/helpers.rb', line 261

def has_selector?(css)
  current.has_selector?(css)
end

#has_text?(string) ⇒ Boolean

Returns whether it's on the page right now.

Parameters:

  • string (String) —

    the text to look for

Returns:

  • (Boolean) —

    whether it's on the page right now



234
235
236
 
# File 'lib/unmagic/browser/console/helpers.rb', line 234

def has_text?(string)
  current.has_text?(string)
end

#help ⇒ nil

What you can type, and what it does.

Returns:

  • (nil) 


309
310
311
312
 
# File 'lib/unmagic/browser/console/helpers.rb', line 309

def help
  puts(Banner.help)
  nil
end

#hover(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

Returns:



167
168
169
 
# File 'lib/unmagic/browser/console/helpers.rb', line 167

def hover(query = nil, **options)
  current.hover(query, **options)
end

#html(target = nil) ⇒ Code

Returns the HTML, syntax-highlighted when shown.

Parameters:

  • target (String, nil) (defaults to: nil) —

    a URL to grab, or nil to read the open session

Returns:

  • (Code) —

    the HTML, syntax-highlighted when shown



180
181
182
 
# File 'lib/unmagic/browser/console/helpers.rb', line 180

def html(target = nil)
  Code.new(target ? browser.html(target) : current.html, language: "html", name: "page")
end

#js(script, *args) ⇒ Object Also known as: evaluate

Returns whatever it returns.

Parameters:

  • script (String) —

    an expression, or a function like "() => document.title"

  • args (Array) —

    arguments for the function form

Returns:

  • (Object) —

    whatever it returns



219
220
221
 
# File 'lib/unmagic/browser/console/helpers.rb', line 219

def js(script, *args)
  current.evaluate(script, *args)
end

#markdown(target = nil) ⇒ Code

Returns the Markdown, syntax-highlighted when shown.

Parameters:

  • target (String, nil) (defaults to: nil) —

    a URL to grab, or nil to read the open session

Returns:

  • (Code) —

    the Markdown, syntax-highlighted when shown



186
187
188
 
# File 'lib/unmagic/browser/console/helpers.rb', line 186

def markdown(target = nil)
  Code.new(target ? browser.markdown(target) : current.markdown, language: "markdown", name: "page")
end

#open(url = nil, **options) ⇒ Unmagic::Browser::Session

Open a page and make it the one every other verb drives. Closes whatever was open first — one session at a time is what a console wants.

Parameters:

  • url (String, nil) (defaults to: nil) —

    the page to open, or nil for a blank one

  • options (Hash) —

    see Unmagic::Browser#open

Returns:



53
54
55
56
 
# File 'lib/unmagic/browser/console/helpers.rb', line 53

def open(url = nil, **options)
  Console.session&.close
  Console.session = browser.open(url, **options)
end

#pdf(target = nil) ⇒ Document

Returns PDF bytes, written to a file when shown.

Parameters:

  • target (String, nil) (defaults to: nil) —

    a URL to print, or nil to print the open session

Returns:

  • (Document) —

    PDF bytes, written to a file when shown



205
206
207
 
# File 'lib/unmagic/browser/console/helpers.rb', line 205

def pdf(target = nil)
  Document.new(target ? browser.pdf(target) : current.pdf, name: "page")
end

#press(key, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • key (Symbol, String) —

    e.g. :enter

  • options (Hash) —

    see Session#press

Returns:



160
161
162
 
# File 'lib/unmagic/browser/console/helpers.rb', line 160

def press(key, **options)
  current.press(key, **options)
end

#reload ⇒ Unmagic::Browser::Session

Returns:



65
66
67
 
# File 'lib/unmagic/browser/console/helpers.rb', line 65

def reload
  current.reload
end

#screenshot(target = nil, full_page: false, selector: nil) ⇒ Image

Returns PNG bytes, drawn in the terminal when shown.

Parameters:

  • target (String, nil) (defaults to: nil) —

    a URL to capture, or nil to shoot the open session

  • full_page (Boolean) (defaults to: false) —

    capture the whole scrollable page

  • selector (String, nil) (defaults to: nil) —

    capture just this element

Returns:

  • (Image) —

    PNG bytes, drawn in the terminal when shown



194
195
196
197
198
199
200
201
 
# File 'lib/unmagic/browser/console/helpers.rb', line 194

def screenshot(target = nil, full_page: false, selector: nil)
  bytes = if target
    browser.screenshot(target, full_page: full_page, selector: selector)
  else
    current.screenshot(full_page: full_page, selector: selector)
  end
  Image.new(bytes)
end

#select(option, from: nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • option (String) —

    the option's visible label, or its value

  • from (String, nil) (defaults to: nil) —

    the select's label or name

  • options (Hash) —

    see Locator.build

Returns:



124
125
126
 
# File 'lib/unmagic/browser/console/helpers.rb', line 124

def select(option, from: nil, **options)
  current.select(option, from: from, **options)
end

#session ⇒ Unmagic::Browser::Session?

Returns the session the verbs are driving.

Returns:



40
41
42
 
# File 'lib/unmagic/browser/console/helpers.rb', line 40

def session
  Console.session
end

#text ⇒ String

Returns the visible text of the page.

Returns:

  • (String) —

    the visible text of the page



174
175
176
 
# File 'lib/unmagic/browser/console/helpers.rb', line 174

def text
  current.text
end

#title ⇒ String

Returns the page's title.

Returns:

  • (String) —

    the page's title



85
86
87
 
# File 'lib/unmagic/browser/console/helpers.rb', line 85

def title
  current.title
end

#uncheck(query = nil, **options) ⇒ Unmagic::Browser::Session

Parameters:

  • query (String, nil) (defaults to: nil) —

    the checkbox's label or name

  • options (Hash) —

    see Locator.build

Returns:



138
139
140
 
# File 'lib/unmagic/browser/console/helpers.rb', line 138

def uncheck(query = nil, **options)
  current.uncheck(query, **options)
end

#url ⇒ String

Returns the URL currently shown.

Returns:

  • (String) —

    the URL currently shown



80
81
82
 
# File 'lib/unmagic/browser/console/helpers.rb', line 80

def url
  current.current_url
end

#use(driver) ⇒ Unmagic::Browser

Switch drivers, closing whatever's open.

Parameters:

Returns:



34
35
36
37
 
# File 'lib/unmagic/browser/console/helpers.rb', line 34

def use(driver)
  Console.reset(driver)
  browser
end

#value(query = nil, **options) ⇒ String?

Returns what's in the field.

Parameters:

  • query (String, nil) (defaults to: nil) —

    the field's label, placeholder, name or id

  • options (Hash) —

    see Locator.build

Returns:

  • (String, nil) —

    what's in the field



212
213
214
 
# File 'lib/unmagic/browser/console/helpers.rb', line 212

def value(query = nil, **options)
  current.value(query, **options)
end

#visit(url) ⇒ Unmagic::Browser::Session

Parameters:

  • url (String) —

    where to go, in the session that's already open

Returns:



60
61
62
 
# File 'lib/unmagic/browser/console/helpers.rb', line 60

def visit(url)
  current.visit(url)
end

#wait_for(**options) ⇒ Unmagic::Browser::Session

Parameters:

Returns:



228
229
230
 
# File 'lib/unmagic/browser/console/helpers.rb', line 228

def wait_for(**options)
  current.wait_for(**options)
end

#within(query = nil, **options) { ... } ⇒ Object

Narrow every verb inside the block to one part of the page.

Parameters:

Yields:

  • with the scope in force

Returns:

  • (Object) —

    whatever the block returns



287
288
289
 
# File 'lib/unmagic/browser/console/helpers.rb', line 287

def within(query = nil, **options, &block)
  current.within(query, **options) { block.call }
end