Login form location utility

Locust 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.

Run npm install @buttercup/locust --save-dev to install as a dev dependency in a Node JS project.

The npm published version of this libary contains both the minified and unminified sources which can be used directly: dist/locust.js and dist/locust.min.js.

When requiring this library directly via @buttercup/locust, the minified version provided.

Locust is a UMD library, so it can be used in a variety of places (such as in the browser, CommonJS2 and AMD systems). You can either import it:

const Locust = require("@buttercup/locust");

Or embed it in a webpage and access it via window.Locust.

Locust exports a couple of useful methods, but the one which provides the most simple approach to logging in is getLoginTarget:

const { getLoginTarget } = Locust;

getLoginTarget().login("myUsername", "myPassword");

The 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).

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.

In the case that you don't want to automatically log in, but still enter the details, you can use the following example:

getLoginTarget().enterDetails("myUsername", "myPassword");

Note that getLoginTarget may return null if no form is found, so you should check for this eventuality.

You can also read the API documentation if you're into that kind of thing.

Locust 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:

const target = getLoginTarget();
target.on("valueChanged", info => {
    if (info.type === "username") {
        console.log("New username:", info.value);
    }
});
// `type` can be "username" or "password"

Login targets subclass EventEmitter, so you can use all other methods provided by their implementation.

You can also listen to form submission:

const target = getLoginTarget();
target.once("formSubmitted", ({ source }) => {
    // `source` will either be "submitButton" or "form"
});

You 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.

To run on HTTPS pages consider using a Chrome extension like Disable Content Security Policy, which will allow injection of local scripts.