Test Playable Ads

Test the generated output at four levels. Use the same file for each applicable test.

Generated output

Do not change the HTML or ZIP file. Change the source project, and then build the output again.

1. Test the package

Read the build report.
Fix each build error.
Check the file name and ZIP structure.
Check the file size and orientation.
Check the resource rules.
Record the file hash.
Check each external URL.

Permit only the host URLs that the selected platform requires.

Extract a ZIP into a new temporary folder. Do not reuse files from an earlier build.

2. Test in a browser

Open the exact HTML entry.
Check that a compressed mesh renders.
Check that its texture renders.
Start the game.
Check that the first interaction does not open the store.
Complete the game.
Press the CTA.
Hide and restore the page.
Check pause and resume for animation, timers, and audio.
Test each configured orientation.
Test muted audio.
Test the WebGL fallback.
Record console errors and network requests.

Render test

A ready message does not prove that the scene renders. Check the canvas pixels.

Agent command

agent-browser --session playable --allow-file-access open file:///absolute/path/to/index.html
agent-browser --session playable set viewport 390 844
agent-browser --session playable errors
agent-browser --session playable console
agent-browser --session playable network requests
agent-browser --session playable screenshot evidence/portrait.png
agent-browser --session playable close

Take a new snapshot after each navigation or dialog. Keep credentials and test evidence outside the upload file.

3. Test in the platform host

Use the validator or preview from the platform procedure. Only the platform host test covers the platform API.

Record these items:

Complete validator result
Each configured orientation
Start, completion, and CTA actions
All platform warnings
File hash and test date

The validator page makes its own network requests. Identify the requests that came from the playable frame.

Agent permissions

An agent can upload an authorized draft and record results. Do not submit, publish, activate, or change spend without permission.

4. Test on devices

Test on iOS and Android. Include one lower-performance device.

Record	Value
Device	Model name
Software	OS and preview-app version
Layout	Orientation and safe zones
Input	Tap, drag, and multi-touch result
Lifecycle	Hide, resume, and audio-interruption result
Performance	Load time, frame pacing, and memory result
Evidence	Screenshots, video, and console output

Use the device test that the platform supplies:

AppLovin Playable Preview
Unity Ad Testing
TikTok QR preview
Meta placement preview
Playturbo QR preview
WeChat Developer Tools Preview

Run Needle tests

From the Needle Engine package, run:

npm run test:playable
cd tests/playwright
npx playwright test tests/plugins/playable-single-html.integration.spec.ts tests/plugins/wechat-platform.integration.spec.ts

These tests build each platform output. They test local loading, textured rendering, host APIs, network requests, and runtime errors.

The WeChat test also runs the generated Mini Game package in the browser host adapter.

Run the platform and device tests after the Needle tests.

Troubleshooting

Error	Action
First tap opens the store	Call `NeedlePlayableAd.open()` only from the install CTA.
Browser test passes but upload fails	Check the profile, ZIP root, URLs, resources, and forbidden globals.
External script found	Check whether the platform requires TikTok SDK, Google Exit API, or MRAID.
Canvas is blank	Find the first decoder or renderer error. Check the canvas pixels.
CTA fails in the platform preview	Check the host API and store URL.