{"id":19534653,"url":"https://github.com/buttercup/locust","last_synced_at":"2025-04-26T14:35:11.243Z","repository":{"id":146446514,"uuid":"114274382","full_name":"buttercup/locust","owner":"buttercup","description":"Login form location \u0026 automation utility","archived":false,"fork":false,"pushed_at":"2024-04-06T19:56:04.000Z","size":1279,"stargazers_count":21,"open_issues_count":13,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-19T16:19:31.764Z","etag":null,"topics":["authentication","buttercup","login","login-automation","login-forms"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/buttercup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2017-12-14T16:43:51.000Z","updated_at":"2024-12-29T01:01:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"cbe5cb25-3abd-4711-bcbf-830968a6c8f8","html_url":"https://github.com/buttercup/locust","commit_stats":{"total_commits":165,"total_committers":3,"mean_commits":55.0,"dds":0.07272727272727275,"last_synced_commit":"802eb74b03517367dca4102926e8f8cad8552ea4"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Flocust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Flocust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Flocust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Flocust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buttercup","download_url":"https://codeload.github.com/buttercup/locust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250681833,"owners_count":21470284,"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":["authentication","buttercup","login","login-automation","login-forms"],"created_at":"2024-11-11T02:15:04.575Z","updated_at":"2025-04-26T14:35:11.207Z","avatar_url":"https://github.com/buttercup.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Locust\n\n\u003e Login form location utility\n\n[![Buttercup](https://cdn.rawgit.com/buttercup-pw/buttercup-assets/6582a033/badge/buttercup-slim.svg)](https://buttercup.pw) ![Tests](https://github.com/buttercup/locust/actions/workflows/test.yml/badge.svg) [![npm version](https://badge.fury.io/js/%40buttercup%2Flocust.svg)](https://www.npmjs.com/package/@buttercup/locust)\n\n## About\n\nLocust helps find **login forms** by searching the DOM for common login form elements. It processes a page and returns _targets_ which can be used for automating logins.\n\n## Installation\n\nRun `npm install @buttercup/locust --save-dev` to install as a dev dependency - as it's designed to be included in a build system, such as with Webpack, it does not need to be a normal dependency.\n\nTypes are included.\n\n## Usage\n\nLocust is an ESM-only library, so you must include it in another project and use a bundler, such as Webpack, to build it for the browser.\n\nLocust exports a couple of useful methods, but the one which provides the most simple approach to logging in is `getLoginTarget`:\n\n```typescript\nimport { getLoginTarget } from \"@buttercup/locust\";\n\ngetLoginTarget().login(\"myUsername\", \"myPassword\");\n```\n\nThe example above enters the username and password in the **best** form found on the page and then proceeds to submit that form (logging the user in).\n\n_To find all forms on a page, use the `getLoginTargets` method instead, which returns an array of login targets. You can then sort through these to find all the different login forms that may exist._\n\nIn the case that you don't want to automatically log in, but still enter the details, you can use the following example:\n\n```typescript\nconst target = getLoginTarget();\nawait target.fillUsername(\"myUsername\");\nawait target.fillPassword(\"myPassword\");\n```\n\nYou can fill in OTPs using the following:\n\n```typescript\nawait target.fillOTP(\"123456\");\n```\n\n_**Note** that `getLoginTarget` may return `null` if no form is found, so you should check for this eventuality._\n\n### Filtering\n\nYou can filter input/form elements picked up by `getLoginTarget` and `getLoginTargets` by passing an element validator callback as the second parameter:\n\n```typescript\nconst target = getLoginTarget(\n    document,\n    () =\u003e true\n);\n```\n\nWhere the callback follows this format:\n\n```typescript\n(feature: LoginTargetFeature, element: HTMLElement) =\u003e boolean;\n```\n\n_Return `false` to ignore the element and `true` to include it. Defaults to `true` for all elements._\n\n### Events\n\nLocust login targets will emit events when certain things happen. To listen for changes to the values of usernames and passwords on forms simply attach event listeners:\n\n```typescript\nconst target = getLoginTarget();\ntarget.on(\"valueChanged\", info =\u003e {\n    if (info.type === \"username\") {\n        console.log(\"New username:\", info.value);\n    }\n});\n// `type` can be \"username\" or \"password\"\n```\n\n\u003e Login targets subclass [`EventEmitter`](https://github.com/primus/eventemitter3), so you can use all other methods provided by their implementation.\n\nYou can also listen to form submission:\n\n```javascript\nconst target = getLoginTarget();\ntarget.once(\"formSubmitted\", ({ source }) =\u003e {\n    // `source` will either be \"submitButton\" or \"form\"\n});\n```\n\n## Development\n\nYou can run `npm run dev` to generate and watch-files to develop Locust. To create a script that outputs dev information, run `npm run dev:inject` and inject the provided script snippet into pages to test Locust. It won't work all of the time if the Buttercup browser extension is running, nor will it work in consecutive executions.\n\nTo run on HTTPS pages consider using a Chrome extension like [Disable Content Security Policy](https://chrome.google.com/webstore/detail/disable-content-security/ieelmcmcagommplceebfedjlakkhpden?hl=en), which will allow injection of local scripts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Flocust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuttercup%2Flocust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Flocust/lists"}