{"id":"evilbocchi/roblox-coverage","name":"roblox-coverage","scope":"evilbocchi","platform":"roblox","description":"Mirrored from the Wally registry.","version":"0.1.1","latest":"0.1.1","versions":["0.1.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"cbe766407473e34a5dce8277685b14bad029bb8cf7ccf821946b788836f9f4af","likes":0,"downloads":0,"install":"forest install evilbocchi/roblox-coverage","url":"https://forest.dev/p/roblox/evilbocchi/roblox-coverage","files":"https://api.forest.dev/ai/package/roblox/evilbocchi/roblox-coverage/files","readme":"# Roblox Coverage\r\n\r\nCode coverage instrumentation for Roblox Luau modules. This library injects lightweight probes into your ModuleScripts at runtime, collects execution hits, and emits an Istanbul-compatible JSON report that you can feed into standard coverage tooling (HTML, lcov, Cobertura, etc.).\r\n\r\n## Features\r\n- Runtime instrumentation of ModuleScripts (no compiler plugin required)\r\n- Istanbul/nyc-compatible JSON output\r\n- Function and branch hit tracking in addition to statements\r\n- Sensible include/exclude defaults (avoids `Packages` and the coverage folder)\r\n- Demo place + script to generate full HTML/text/LCOV/Cobertura reports locally\r\n\r\n## How it works\r\n1. `coverage.instrument()` walks your include roots, injects `_G.__covhit`, `_G.__covfn`, and `_G.__covbranch` calls into ModuleScript sources, and tracks IDs per line/function/branch.\r\n2. Your code runs normally; probes increment counters in `_G.__COVERAGE__`.\r\n3. `coverage.istanbul()` converts the collected data to an Istanbul report object you can serialize and post-process with `istanbul-lib-*` or CI tools.\r\n\r\n## Quick start (demo)\r\nPrereqs: Node.js, Roblox Studio\r\n\r\nIf you do not have Roblox Studio installed, you can specify a `ROBLOSECURITY` environment variable of a throwaway account to run luau on the cloud.\r\n\r\n```bash\r\nnpm install\r\nnpm run demo\r\n```\r\n\r\nThe demo will:\r\n- Build the example place via Rojo to `demo/place.rbxl`\r\n- Run `demo/test.luau` with rbxluau, which instruments and exercises sample modules\r\n- Emit Istanbul JSON to `demo/coverage/coverage-final.json`\r\n- Generate HTML, lcov, Cobertura, text, and JSON summary reports into `demo/coverage/`\r\n\r\nOpen `demo/coverage/index.html` in a browser to explore the report.\r\n\r\n## Using in your experience\r\n```lua\r\nlocal coverage = require(game:GetService(\"ReplicatedStorage\").coverage)\r\n\r\n-- Instrument common services by default; you can pass explicit roots.\r\ncoverage.instrument(\r\n    {\r\n        game:GetService(\"ServerScriptService\"),\r\n        game:GetService(\"ReplicatedStorage\"),\r\n        game:GetService(\"ServerStorage\"),\r\n        game:GetService(\"StarterPlayer\"),\r\n        game:GetService(\"StarterGui\"),\r\n    },\r\n    {\r\n        game:GetService(\"ReplicatedStorage\"):FindFirstChild(\"Packages\"),\r\n    }\r\n)\r\n```\r\n\r\n1. Run your tests or gameplay to collect coverage.\r\n2. Export the report where you need it (e.g. to HttpService, DataStore, or a file if running in a CLI environment):\r\n\r\n```lua\r\nlocal HttpService = game:GetService(\"HttpService\")\r\nlocal report = coverage.istanbul()\r\nlocal json = HttpService:JSONEncode(report)\r\n-- Persist json as needed\r\n```\r\n\r\n## Notes\r\n- This library destructively modifies ModuleScript sources. It's recommended to only enable coverage instrumentation in test environments.\r\n- The instrumentation also adds overhead; expect slower execution times when coverage is enabled.\r\n- Coverage JSON uses Roblox datamodel paths, not filesystem paths. You may need to map these paths when integrating with external tools.","readmeTruncated":false}