{"id":16965020,"url":"https://github.com/propensive/tarantula","last_synced_at":"2025-04-11T23:04:51.574Z","repository":{"id":39483162,"uuid":"405930558","full_name":"propensive/tarantula","owner":"propensive","description":"Drive a web browser with the WebDriver protocol for Scala","archived":false,"fork":false,"pushed_at":"2025-02-11T23:56:13.000Z","size":2320,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-20T01:38:46.240Z","etag":null,"topics":["browser-automation","dom","scala","webdriver"],"latest_commit_sha":null,"homepage":"https://propensive.com/tarantula/","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/propensive.png","metadata":{"files":{"readme":".github/readme.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-13T10:38:35.000Z","updated_at":"2025-02-11T23:56:16.000Z","dependencies_parsed_at":"2023-02-19T17:00:45.939Z","dependency_job_id":"18026dae-4cdf-46ff-a963-4d451c874120","html_url":"https://github.com/propensive/tarantula","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/propensive%2Ftarantula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Ftarantula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Ftarantula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Ftarantula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/propensive","download_url":"https://codeload.github.com/propensive/tarantula/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239805887,"owners_count":19700203,"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":["browser-automation","dom","scala","webdriver"],"created_at":"2024-10-13T23:44:50.336Z","updated_at":"2025-02-20T08:31:39.234Z","avatar_url":"https://github.com/propensive.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"[\u003cimg alt=\"GitHub Workflow\" src=\"https://img.shields.io/github/actions/workflow/status/propensive/tarantula/main.yml?style=for-the-badge\" height=\"24\"\u003e](https://github.com/propensive/tarantula/actions)\n[\u003cimg src=\"https://img.shields.io/discord/633198088311537684?color=8899f7\u0026label=DISCORD\u0026style=for-the-badge\" height=\"24\"\u003e](https://discord.com/invite/MBUrkTgMnA)\n\u003cimg src=\"/doc/images/github.png\" valign=\"middle\"\u003e\n\n# Tarantula\n\n__Drive a web browser using the WebDriver protocol__\n\n_Tarantula_ makes it possible to interact with a web browser through a programmatic interface. It\nprovides an immutable API for controlling the web browser from Scala, through the WebDriver\nprotocol.\n\n## Features\n\n- simulate keypresses and mouse clicks in a web browser\n- automatically launch Chrome or Firefox programmatically\n- uses the standard WebDriver protocol\n- intuitive, but typesafe syntax\n\n\n## Availability\n\n\n\n\n\n\n\n## Getting Started\n\n### Browser Sessions\n\n_Tarantula_ makes it possible to control a web browser programmatically from Scala. Currently [Firefox](https://www.mozilla.org/en-GB/firefox/new/) and [Chrome](https://www.google.com/chrome/) are supported.\n\nAll browser operations take place in a _session_, which may be started by calling the `session` method, specifying a port number, on\na `Browser` object; either `Chrome` or `Firefox`. For example:\n```scala\nFirefox.session(8120):\n  // Browser actions are carried out in this scope\n```\n\n### Simple navigation\n\nWithin the session body, the `browser` object, may be accessed and used to control the newly-launched browser.\n\nThe `browser` object is an instance of `WebDriver#Session`, and includes several navigational methods:\n- `navigateTo(url)` - to send the browser to a particular URL\n- `refresh()` - to refresh the page\n- `back()` - to go back to the previous page\n- `forward()` - to go forward (assuming we have already gone back at least once)\n\nThe `title()` method will also return the page title, and `url()` the current URL, as `Text` instances.\n\n### Acessing Elements\n\nWithin a particular page, it's possible to access an element with the `element` method, which takes, as a parameter, a\nway of locating that element, of which several different types are valid:\n- `Text`: finds an element by its link text\n- `Selector`: type from [Cataclysm](https://github.com/propensive/cataclysm), which find a value by CSS selection\n- `TagType`, `DomId`, `Cls`: types from [Honeycomb](https://github.com/propensive/honeycomb), which finds a value by an HTML tag, DOM ID or CSS class\n\nFor example, the link containing the text `\"here\"` could be selected with, `browser.element(t\"here\")` or the element which is an\ninstance of an `\u003cimg\u003e` HTML tag could be found with `browser.element(Img)`, where the `Img` value is defined in Honeycomb. In both\ncases an `Element` instance will be returned, or an exception will be thrown if no matching element exists on the page.\n\nHTML has a tree-based structure, so it's possible to select one element within another with repeated applications of the\n`Element#element` method, for example,\n```scala\nval link = browser.element(Nav).element(id\"menu\").element(t\"About\")\n```\nwould find the link containing the text `About` in the element with ID `menu` which is inside a `\u003cnav\u003e` HTML element.\n\n### Accessing multiple elements\n\nOften it's useful to find all elements on a page, which is served by the `/` method of `browser`, `Element` and as an\nextension on `List[Element]`. Although the method is defined on three types, it always returns a `List[Element]`, and since\nthis is one of the types defining `/`, it is easy to progressively filter a selection of elements to a single one, with\nrepeated applications. The infix syntax is particularly intuitive. For example,\n```scala\nfor elem \u003c- browser / id\"menu\" / Li / cls\"checkbox\" do elem.click()\n```\nwould simulate a click on every element with the `checkbox` CSS class inside an `\u003cli\u003e` tag in the element with ID `menu`.\n\n\n\n\n\n## Status\n\nTarantula is classified as __fledgling__. For reference, Soundness projects are\ncategorized into one of the following five stability levels:\n\n- _embryonic_: for experimental or demonstrative purposes only, without any guarantees of longevity\n- _fledgling_: of proven utility, seeking contributions, but liable to significant redesigns\n- _maturescent_: major design decisions broady settled, seeking probatory adoption and refinement\n- _dependable_: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version `1.0.0` or later\n- _adamantine_: proven, reliable and production-ready, with no further breaking changes ever anticipated\n\nProjects at any stability level, even _embryonic_ projects, can still be used,\nas long as caution is taken to avoid a mismatch between the project's stability\nlevel and the required stability and maintainability of your own project.\n\nTarantula is designed to be _small_. Its entire source code currently consists\nof 183 lines of code.\n\n## Building\n\nTarantula will ultimately be built by Fury, when it is published. In the\nmeantime, two possibilities are offered, however they are acknowledged to be\nfragile, inadequately tested, and unsuitable for anything more than\nexperimentation. They are provided only for the necessity of providing _some_\nanswer to the question, \"how can I try Tarantula?\".\n\n1. *Copy the sources into your own project*\n   \n   Read the `fury` file in the repository root to understand Tarantula's build\n   structure, dependencies and source location; the file format should be short\n   and quite intuitive. Copy the sources into a source directory in your own\n   project, then repeat (recursively) for each of the dependencies.\n\n   The sources are compiled against the latest nightly release of Scala 3.\n   There should be no problem to compile the project together with all of its\n   dependencies in a single compilation.\n\n2. *Build with [Wrath](https://github.com/propensive/wrath/)*\n\n   Wrath is a bootstrapping script for building Tarantula and other projects in\n   the absence of a fully-featured build tool. It is designed to read the `fury`\n   file in the project directory, and produce a collection of JAR files which can\n   be added to a classpath, by compiling the project and all of its dependencies,\n   including the Scala compiler itself.\n   \n   Download the latest version of\n   [`wrath`](https://github.com/propensive/wrath/releases/latest), make it\n   executable, and add it to your path, for example by copying it to\n   `/usr/local/bin/`.\n\n   Clone this repository inside an empty directory, so that the build can\n   safely make clones of repositories it depends on as _peers_ of `tarantula`.\n   Run `wrath -F` in the repository root. This will download and compile the\n   latest version of Scala, as well as all of Tarantula's dependencies.\n\n   If the build was successful, the compiled JAR files can be found in the\n   `.wrath/dist` directory.\n\n## Contributing\n\nContributors to Tarantula are welcome and encouraged. New contributors may like\nto look for issues marked\n[beginner](https://github.com/propensive/tarantula/labels/beginner).\n\nWe suggest that all contributors read the [Contributing\nGuide](/contributing.md) to make the process of contributing to Tarantula\neasier.\n\nPlease __do not__ contact project maintainers privately with questions unless\nthere is a good reason to keep them private. While it can be tempting to\nrepsond to such questions, private answers cannot be shared with a wider\naudience, and it can result in duplication of effort.\n\n## Author\n\nTarantula was designed and developed by Jon Pretty, and commercial support and\ntraining on all aspects of Scala 3 is available from [Propensive\nO\u0026Uuml;](https://propensive.com/).\n\n\n\n## Name\n\n__Tarantulas__ are spiders, known for making webs, and Tarantula is a library for the WebDriver protocol.\n\nIn general, Soundness project names are always chosen with some rationale,\nhowever it is usually frivolous. Each name is chosen for more for its\n_uniqueness_ and _intrigue_ than its concision or catchiness, and there is no\nbias towards names with positive or \"nice\" meanings—since many of the libraries\nperform some quite unpleasant tasks.\n\nNames should be English words, though many are obscure or archaic, and it\nshould be noted how willingly English adopts foreign words. Names are generally\nof Greek or Latin origin, and have often arrived in English via a romance\nlanguage.\n\n## Logo\n\nThe logo represents the eight legs of a tarantula.\n\n## License\n\nTarantula is copyright \u0026copy; 2025 Jon Pretty \u0026 Propensive O\u0026Uuml;, and\nis made available under the [Apache 2.0 License](/license.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Ftarantula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpropensive%2Ftarantula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Ftarantula/lists"}