{"id":18103132,"url":"https://github.com/cavalle/chrome_remote","last_synced_at":"2025-04-05T09:06:38.557Z","repository":{"id":59152064,"uuid":"97321423","full_name":"cavalle/chrome_remote","owner":"cavalle","description":"DISCONTINUED - A client implementation of the Chrome DevTools Protocol in Ruby","archived":false,"fork":false,"pushed_at":"2022-02-22T12:47:23.000Z","size":59,"stargazers_count":122,"open_issues_count":5,"forks_count":25,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T08:06:19.355Z","etag":null,"topics":["chrome","devtools","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cavalle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-15T14:34:46.000Z","updated_at":"2024-11-14T13:19:53.000Z","dependencies_parsed_at":"2022-09-13T11:00:45.693Z","dependency_job_id":null,"html_url":"https://github.com/cavalle/chrome_remote","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavalle%2Fchrome_remote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavalle%2Fchrome_remote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavalle%2Fchrome_remote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cavalle%2Fchrome_remote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cavalle","download_url":"https://codeload.github.com/cavalle/chrome_remote/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312077,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome","devtools","ruby"],"created_at":"2024-10-31T22:10:25.387Z","updated_at":"2025-04-05T09:06:38.025Z","avatar_url":"https://github.com/cavalle.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discontinued\n\nThis library is not actively maintained. Check https://github.com/rubycdp/ferrum for a replacement.\n\n# ChromeRemote\n\n[![Gem Version](https://img.shields.io/gem/v/chrome_remote.svg?style=for-the-badge)](https://rubygems.org/gems/chrome_remote)\n[![Build Status](https://img.shields.io/travis/cavalle/chrome_remote/master?style=for-the-badge)](https://travis-ci.org/cavalle/chrome_remote)\n\nChromeRemote is a client implementation of the [Chrome DevTools Protocol][1] in Ruby. It lets you remotely control, instrument, inspect, debug and profile instances of Chrome/Chromium based browsers from your Ruby code.\n\n[1]: https://chromedevtools.github.io/devtools-protocol/\n\n## Usage example\n\nThe following snippet navigates to `https://github.com`, dumps any request made while loading the page, and takes a screenshot once the page is loaded:\n\n```ruby\nrequire 'chrome_remote'\nrequire 'base64'\n\nchrome = ChromeRemote.client\n\n# Enable events\nchrome.send_cmd \"Network.enable\"\nchrome.send_cmd \"Page.enable\"\n\n# Setup handler to log network requests\nchrome.on \"Network.requestWillBeSent\" do |params|\n  puts params[\"request\"][\"url\"]\nend\n\n# Navigate to github.com and wait for the page to load\nchrome.send_cmd \"Page.navigate\", url: \"https://github.com\"\nchrome.wait_for \"Page.loadEventFired\"\n\n# Take page screenshot\nresponse = chrome.send_cmd \"Page.captureScreenshot\"\nFile.write \"screenshot.png\", Base64.decode64(response[\"data\"])\n```\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'chrome_remote'\n```\n\nAnd then execute:\n\n```\n$ bundle\n```\n\nOr install it yourself as:\n\n```\n$ gem install chrome_remote\n```\n\n## Usage\n\nTo use ChromeRemote, you'll need a Chrome instance running on a known port (`localhost:9222` is the default), using the `--remote-debugging-port` flag.\n\nIn Linux:\n\n```\n$ google-chrome --remote-debugging-port=9222\n```\n\nIn macOS:\n\n```\n$ /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222\n```\n\nIn Windows 7 or above:\n\n```\n\u003e \"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe\" --remote-debugging-port=9222\n```\n\n#### Headless mode\n\nAdditionally, since version 59, you can use the `--headless` flag to start Chrome in [headless mode][2]\n\n[2]: https://developers.google.com/web/updates/2017/04/headless-chrome\n\n### Using the ChromeRemote API\n\nThe [Chrome DevTools Protocol][1] is divided into a number of domains ([Page][3], [DOM][4], [Debugger][5], [Network][6], etc.). Each domain defines a number of **commands** it supports and **events** it generates.\n\nChromeRemote provides a simple API that lets you send commands, and handle events of any of the domains in the protocol.\n\nTo start with, you need an instance of the `ChromeRemote` class.\n\n```ruby\nchrome = ChromeRemote.client(\n  host: 'localhost', # optional (default: localhost). Host of the Chrome remote server\n  port: 9222,        # optional (default: 9222). Port of the Chrome remote server\n  new_tab: false     # optional (default: false). Whether to use the browser's current tab or a new one\n)\n```\n\nNow, to send commands, ChromeRemote provides the `ChromeRemote#send_cmd` method. For example, this is how you make Chrome navigate to a url by sending the [Page.navigate][7] command:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Page.navigate\", url: \"https://github.com\"\n# =\u003e {:frameId=\u003e1234}\n```\n\nTo tackle events, you have several options but, first of all, you need to enable events for any domain you're interested in. You only need to do this once per domain:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Network.enable\"\n```\n\nNow, you can use the `ChromeRemote#on` method to subscribe to an event. For instance, this is how you subscribe to the [Network.requestWillBeSent][8] event:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Network.enable\"\n\nchrome.on \"Network.requestWillBeSent\" do |params|\n  puts params[\"request\"][\"url\"]\nend\n```\n\nWith the `ChromeRemote#wait_for` method, you can wait until the next time a given event is triggered. For example, the following snippet navigates to a page and waits for the [Page.loadEventFired][9] event to happen:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Page.navigate\", url: \"https://github.com\"\n\nchrome.wait_for \"Page.loadEventFired\"\n# =\u003e {:timestamp=\u003e34}\n```\n\nYou can also use `wait_for` with a block to implement a custom matcher on the event names and params you're waiting for:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Page.navigate\", url: \"https://github.com\"\n\nclient.wait_for do |event_name, event_params|\n  event_name == \"Page.lifecycleEvent\" \u0026\u0026 event_params[\"name\"] == \"load\"\nend\n```\n\nIn certain occasions, after you have subscribed to one or several events, you may just want to process messages indefinitely, and let the event handlers process any event that may happen until you kill your script. For those cases, ChromeRemote provides the `ChromeRemote#listen` method:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Network.enable\"\n\nchrome.on \"Network.requestWillBeSent\" do |params|\n  puts params[\"request\"][\"url\"]\nend\n\nchrome.listen # will process incoming messages indefinitely\n```\n\nFinally, you have `ChromeRemote#listen_until` that will listen and process incoming messages but only until a certain condition is met. For instance, the following snippet waits until 5 requests are received and then continues:\n\n```ruby\nchrome = ChromeRemote.client\nchrome.send_cmd \"Network.enable\"\n\nrequests = 0\nchrome.on \"Network.requestWillBeSent\" do |params|\n  requests += 1\nend\n\nchrome.listen_until { requests == 5 }\n\n# do other stuff\n```\n\n[3]: https://chromedevtools.github.io/devtools-protocol/tot/Page/\n[4]: https://chromedevtools.github.io/devtools-protocol/tot/DOM/\n[5]: https://chromedevtools.github.io/devtools-protocol/tot/Debugger/\n[6]: https://chromedevtools.github.io/devtools-protocol/tot/Network/\n[7]: https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-navigate\n[8]: https://chromedevtools.github.io/devtools-protocol/tot/Network/#event-requestWillBeSent\n[9]: https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-loadEventFired\n\n### Logger\n\nTo log all incoming and outgoing messages you can pass [Logger](https://github.com/ruby/logger) compatible instance to client.\n\n```ruby\nclient = ChromeRemote.client(logger: Logger.new($stdout))\nclient.send_cmd('Page.enable')\n# I, [2019-03-06T22:32:28.433643 #5070]  INFO -- : SEND ► {\"method\":\"Page.enable\",\"params\":{},\"id\":1}\n# I, [2019-03-06T22:32:28.440294 #5070]  INFO -- : ◀ RECV {\"id\":1,\"result\":{}}\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment or any of the scripts in the `/examples` directory (e.g. `bundle exec ruby examples/network_dump_and_screenshot.rb`).\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\nTo release a new version (if you're a maintainer), update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/cavalle/chrome_remote.\n\nThis project is intended to be a safe, welcoming space for collaboration, and contributors are expected to follow the [code of conduct](https://github.com/cavalle/chrome_remote/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavalle%2Fchrome_remote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcavalle%2Fchrome_remote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcavalle%2Fchrome_remote/lists"}