# arce

> (A)rbitrary (R)emote (C)ode (E)xecutor: Experimental tool for browser agnostic e2e testing.

Latest version **0.5.0** (published 2023-03-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install arce
pnpm add arce
yarn add arce
bun add arce
```

Provides the command `arce`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2023-03-31 |
| First published | 2021-05-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 4 |
| Unpacked size | 30.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Andreas Schoch |
| Maintainers | galvandi |
| Keywords | inject, testing, e2e, automate, control |

## Links

- npm: https://www.npmjs.com/package/arce
- Repository: https://github.com/andreas-schoch/arce
- Homepage: https://github.com/andreas-schoch/arce#readme
- Issues: https://github.com/andreas-schoch/arce/issues
- npm.io page: https://npm.io/package/arce

## Dependencies (4)

- [ws](https://npm.io/package/ws.md) ^8.13.0
- [yargs](https://npm.io/package/yargs.md) ^17.6.0
- [esprima](https://npm.io/package/esprima.md) ^4.0.1
- [express](https://npm.io/package/express.md) ^4.18.2

## Alternatives

- [@snazzah/davey](https://npm.io/package/@snazzah/davey.md) — 1.5M weekly downloads
- [@vendure/testing](https://npm.io/package/@vendure/testing.md) — 8.3K weekly downloads
- [vue-simple-context-menu](https://npm.io/package/vue-simple-context-menu.md) — 6.6K weekly downloads
- [cypress-webpack-preprocessor-v5](https://npm.io/package/cypress-webpack-preprocessor-v5.md) — 2.1K weekly downloads
- [@backstage/plugin-catalog-backend-module-puppetdb](https://npm.io/package/@backstage/plugin-catalog-backend-module-puppetdb.md) — 1.3K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2023-03-31
- 0.4.2 — 2022-11-04
- 0.4.1 — 2022-10-30
- 0.4.0 — 2022-10-22
- 0.3.1 — 2022-10-20
- 0.3.0 — 2022-10-18
- 0.2.6 — 2022-10-16
- 0.2.5 — 2022-10-02
- 0.2.4 — 2022-10-01
- 0.2.3 — 2022-09-29
- 0.2.2 — 2022-09-29
- 0.2.1 — 2022-09-25
- 0.2.0 — 2022-09-25
- 0.1.5 — 2022-09-23
- 0.1.4 — 2022-09-23
- … 5 more at https://npm.io/package/arce/versions

## README

ARCE: Arbitrary Remote Code Executor
=======================

[![npm version](https://badge.fury.io/js/arce.svg)](https://badge.fury.io/js/arce)
[![GitHub license](https://img.shields.io/github/license/andreas-schoch/arce.svg)](https://github.com/andreas-schoch/arce/blob/main/LICENSE)
![Coverage Badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/andreas-schoch/e7afe8a31c8fde66fc11902f7aad7792/raw/arce__heads_main.json)

An experimental attempt to send arbitrary JavaScript commands to a webapp via a websocket server proxy.

**Should not be used anywhere near production or for any malicious purposes!**

## How is this useful?

This package tries to be a browser-agnostic alternative to tools like puppeteer, playwright, selenium etc.,
which either use the chrome devtools protocol, webdrivers and/or need the browser to be opened with specific args to
work.

Any of the above-mentioned tools should likely be preferred over 'arce', but in scenarios where you have limited
control over how a browser is opened (for example: a webapp shown in a webview embedded in some desktop app) and need to
e2e test a variety of otherwise unsupported browsers, this kind of websocket proxy might work.

## Install

```bash
npm install arce
```

or

```bash
yarn add arce
```

## Usage

1. Start websocket server proxy:
   ```shell
   npx arce --ssl_cert=example.crt --ssl_key=example.key
   ```

2. Include this script in your index.html to automatically open websocket connection:
   ```html
   <script src="https://localhost:12000/client"></script>
   ```
3. Open https://localhost:12000/public/example-client.html (has the above script already included)
4. Send a POST request to https://localhost:12000/command?foo=hello&bar=world with the following body:
   ```javascript
   async ({waitUntil, capture, done, global, scriptContext}) => {
     capture(scriptContext.foo);
     setTimeout(() => document.querySelector('button').click(), 1500);
     // waits for list to be visible
     const list = await waitUntil(() => document.querySelector('ul:not(.hidden)'));
     let i = 0;
     // Scroll to random list item every 0.3s
     const handler = setInterval(() => {
       const randIndex = Math.floor(Math.random() * list.children.length);
       const li = list.children[randIndex];
       capture(li.innerText); // value to be included with the http response
       li.scrollIntoView({ behavior: "smooth", block: "center" });
       if (++i > 10) {
         clearInterval(handler);
         document.body.style.backgroundColor = 'salmon';
         capture(scriptContext.bar);
         done();
       }
     }, 300);
   };
   ```
   Which will result in the following response:
   ```json
   {
     "status": 200,
     "script": "<The script fn (as a string) sent within body>",
     "awaitId": "a35339e3-14d6-48ec-bb2b-0cdc7c81f363",
     "scriptContext": {"foo":  "hello", "bar":  "world"},
     "captures": [
       "hello",
       "Item 07",
       "Item 01",
       "Item 05",
       "Item 08",
        "...",
        "...",
       "world"
     ]
   }
   ```
   The code sent within the POST request is run directly on the connected client, so you have pretty much full access
   to the runtime to automate things and make assertions.

## License

MIT

---
_Source: https://npm.io/package/arce · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._