Skip to content

Commit

Permalink
simplify locust implementation
Browse files Browse the repository at this point in the history
  • Loading branch information
smithki committed Aug 30, 2023
1 parent d734b04 commit 9537b27
Show file tree
Hide file tree
Showing 19 changed files with 399 additions and 912 deletions.
50 changes: 15 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,48 +16,28 @@ Locust helps find **login forms** by searching the DOM for common login form ele
## Usage

```ts
import { getLoginTarget } from "@withuno/locust";
const { getLoginTarget } = Locust;
import { LoginTarget } from "@withuno/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._
const target = LoginTarget.find();

In the case that you don't want to automatically log in, but still enter the details, you can use the following example:
if (target) {
const form = target.get("form");
const usernameInput = target.get("username");
const passwordInput = target.get("password");
const submitButton = target.get("submit");

> **Note**
> `getLoginTarget` may return `null` if no form is found.
```ts
getLoginTarget().enterDetails("myUsername", "myPassword");
usernameInput.value = "myUsername";
passwordInput.value = "myPassword";
submitButton.click();
}
```

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

### Events

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:

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

You can also listen to form submissions:
_To find all forms on a page, use the `LoginTarget.findAll()` 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._

```ts
const target = getLoginTarget();
target.events.once("formSubmitted", ({ source }) => {
// `source` will either be "submitButton" or "form"
});
```
> [!NOTE]
> `LoginTarget.find()` may return `null` if no form is found.
---

Expand Down
Loading

0 comments on commit 9537b27

Please sign in to comment.