Skip to content

docs(apify-actor-development): add remote-first guidance for Playwright Actors #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
DaveHanns wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs(apify-actor-development): add remote-first guidance for Playwright Actors #62

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions skills/apify-actor-development/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,37 @@ This file should contain the input parameters defined in your `.actor/input_sche
- To verify results on Apify Console, you must deploy the Actor with `apify push` and then run it on the platform.
- Do **not** rely on checking Apify Console to verify results from local runs — instead, inspect the local `storage/` directory or check the Actor's log output.

## Testing Playwright (and other browser-based) Actors

**Prefer remote-first testing for any browser-based Actor.** Playwright bundles Chromium, but running it locally requires a set of native system libraries (`glibc`, `libnss3`, `libatk`, fonts, and more). Many agent sandboxes, minimal containers, and CI runners are missing these — so `apify run` for a Playwright Actor fails in ways that look like the code is broken, when the environment is really the problem. Typical failure signatures include:

```
browserType.launch: Failed to launch: Error: spawn .../chrome-headless-shell ENOENT
ls: /lib64/ld-linux-x86-64.so.2: No such file or directory
su: must be suid to work properly. Failed to install browser dependencies.
```

Rather than fighting the sandbox, deploy and run remotely — the Apify platform's Actor images already have every browser dependency preinstalled.

**Recommended workflow for browser-based Actors:**

1. Skip `apify run` locally. Do everything else (schema, code, README) as usual.
2. Deploy with `apify push`.
3. Trigger a real run with `apify call <actor> --input-file input.json` (or inline `--input '{...}'`).
4. Inspect the run's log, dataset, and key-value store output on Apify Console or via `apify runs ls` + `apify api`.

**Sandbox capability check.** If you want to decide programmatically whether the current environment can run Playwright locally, probe for the dynamic linker Playwright's bundled Chromium needs:

```bash
if [ ! -e /lib64/ld-linux-x86-64.so.2 ] && [ ! -e /lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 ]; then
echo "Local browsers unlikely to launch here — use apify push + apify call instead."
fi
```

**Do not run `npx playwright install-deps` in unprivileged environments.** It requires `sudo` / root to install apt packages and will fail loudly (`su: must be suid to work properly`) inside most agent sandboxes and rootless containers. This is expected — treat it as a signal to move to remote testing, not something to work around.

Non-browser Actors (Cheerio, plain HTTP, Python `requests`, etc.) are unaffected — `apify run` remains the right local loop for them.

## Standby mode

Standby mode enables Actors to work as API servers - they remain ready in the background to handle HTTP requests.
Expand Down
Loading