{"id":23792481,"url":"https://github.com/se2p/whisker","last_synced_at":"2025-09-06T10:32:44.883Z","repository":{"id":80478211,"uuid":"150123747","full_name":"se2p/whisker","owner":"se2p","description":"A Testing Utility for Scratch 3.0","archived":false,"fork":false,"pushed_at":"2024-02-23T10:44:37.000Z","size":35861,"stargazers_count":21,"open_issues_count":0,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-12-29T16:39:00.892Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/se2p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-09-24T15:20:01.000Z","updated_at":"2024-10-25T18:58:40.000Z","dependencies_parsed_at":"2024-02-23T11:48:20.743Z","dependency_job_id":null,"html_url":"https://github.com/se2p/whisker","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2Fwhisker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2Fwhisker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2Fwhisker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2Fwhisker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/se2p","download_url":"https://codeload.github.com/se2p/whisker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232115683,"owners_count":18474815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-01T18:35:17.926Z","updated_at":"2025-01-01T18:35:18.494Z","avatar_url":"https://github.com/se2p.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Whisker Logo](logos/whisker-text-logo.png)\n\nWhisker is an automated testing framework for [Scratch](https://scratch.mit.edu/) projects.\n\n\n\n## Description\n\nBlock-based programming environments like *Scratch* foster engagement\nwith computer programming and are used by millions of young learners.\nScratch allows learners to quickly create entertaining programs and\ngames, while eliminating syntactical program errors that could\ninterfere with progress.\n\nHowever, functional programming errors may still lead to incorrect\nprograms, and learners and their teachers need to identify and\nunderstand these errors. This is currently an entirely manual process.\n\nWhisker provides automated and property-based testing functionality for Scratch programs.\n\n\n## Building Whisker\n\nWhisker requires Node.js v18.18.0 and is built using the [yarn](https://classic.yarnpkg.com/lang/en/) (classic) package manager.\n\nAfter cloning the repository, install all dependencies using:\n\n```bash\nyarn install\n```\n\nNow you can build the application using:\n```bash\nyarn build\n```\n\n## Running Whisker\n\nAfter building Whisker, simply open 'whisker-web/dist/index.html' in your browser (e.g. Firefox)\n\n```bash\nfirefox whisker-web/dist/index.html\n```\n\nThe Servant is a wrapper around the web client, allowing to run tests automatically in a headless environment\n(via chrome-headless / [puppeteer](https://github.com/puppeteer/puppeteer)). It is called the Servant as in\n\"Cats don't have owners they have servants\".\n\nTo use Whisker on the command line, you can use the Servant node frontend as follows:\n\n```bash\nnode servant run -s \u003cScratch project file\u003e -t \u003ctest file\u003e\n```\n\nAn overview of options is provided using `node servant help`:\n\n```bash\nUsage: node servant [options] [command]\n\nA Testing Utility for Scratch 3.0\n\nOptions:\n  -h, --help                display help for command\n  -V, --version             output the version number\n\nCommands:\n  open [options]            open the Whisker web interface\n  dynamic [options]         dynamic test suites using Neuroevolution\n  generate [options]        generate Whisker test suites\n  help [options] [command]  display help for command\n  model [options]           test with model\n  run [options]             run Whisker tests\n  witness [options]         generate and replay error witnesses\n```\nTo show further help, additionally pass the name of the command you are interested in, e.g.,\nthe `run` command: `node servant help run`.\n```bash\nUsage: node servant run [options]\n\nrun Whisker tests\n\nOptions:\n  -a, --acceleration \u003cInteger\u003e        acceleration factor (default: 1)\n  -d, --headless                      run headless (\"d\" like in \"decapitated\") (default: false)\n  -e, --mutants-download-path \u003cPath\u003e  where generated mutants should be saved\n  -h, --help                          display help for command\n  -j, --number-of-jobs \u003cInteger\u003e      number of jobs (Chromium tabs) for test execution (default: 1)\n  -k, --console-forwarded             forward browser console output\n  -l, --live-log                      print new log output regularly\n  -m, --mutators \u003cString...\u003e          mutation operators to apply\n  -o, --live-output-coverage          print new coverage output regularly\n  -s, --scratch-path \u003cPath\u003e           path to file (\".sb3\") or folder with scratch application(s)\n  -t, --test-path \u003cPath\u003e              path to Whisker tests to run (\".js\")\n  -v, --csv-file \u003cPath\u003e               create CSV file with results\n  -z, --seed \u003cString\u003e                 custom seed for Scratch-VM\n  -et, --executionTrace               whether and execution trace should be recorded and downloaded (default: false)\n  -rec, --state-action-recorder       record the program execution as a json file when running with the `open` command\n```\n\nTo run tests in accelerated mode, provide an acceleration factor using the option `-a`. We recommend using an\nacceleration factor of at most 10, as very low execution times may lead to non-deterministic program behaviour.\n\nFor example, the following command runs tests with a 10-fold speedup and two parallel executions in a headless chrome\ninstance:\n\n```bash\nnode servant run -s project.sb3 -t tests.js -a 10 -d -j 2\n```\n\n## Using Docker (Headless Mode)\n\nAlternatively, you can build and run Whisker in headless mode using docker. This can be beneficial if you want to\nconduct large-scale experiments on a computing cluster. To this, create a Docker image for Whisker, for example using\nthe command\n```bash\ndocker build -t whisker .\n```\nNow, you can run the dockerized version of Whisker via\n```bash\ndocker run whisker \u003cadditional arguments\u003e\n```\nThe main entry point to the container is the wrapper script `whisker-docker.sh`, which calls Whisker's servant in\nheadless mode (using the flags `-d`, `-k` and `-l`, among others.) Any `\u003cadditional arguments\u003e` given by the user will\nbe forwarded by the script to the servant.\n\nIn case you want to copy the artefacts created by Whisker (including redirection of stdout and stderr) to files in a\nwritable bind mount, you can achieve this for example as follows:\n```bash\ndocker run -v \"/on/the/host:/inside/the/container\" whisker /inside/the/container -- \u003cWhikser arguments\u003e\n```\nThis will mount the directory `/on/the/host` as `/inside/the/container`, instruct Whisker to copy its output (such as\ngenerated test files and log messages) to files in `/inside/the/container`, and make them accessible to you in the\ndirectory `/on/the/host`.\n\n## Writing Tests\n\nDetails on writing Whisker tests in JavaScript can be found\n[here](HOWTO.md).\n\n## Generating Tests Automatically\n\nThe web interface provides the possibility to automatically generate tests. In the web interface, choose an appropriate\nsearch configuration (examples can be found in the `config` directory), and click `Test Generation`. Warning: This may\ntake a while! Once the search has completed, the generated tests are loaded into the editor window.\n\nIf you run test generation with Servant (command line option `-g`), at the end of the search a file called `tests.js`\nis created in the current directory which contains the tests. These can now be loaded into Whisker.\n\n## Contributors\n\nWhisker is developed at the\n[Chair of Software Engineering II](https://www.fim.uni-passau.de/lehrstuhl-fuer-software-engineering-ii/)\nof  the [University of Passau](https://www.uni-passau.de).\n\nContributors:\n\nAdina Deiner\\\nPatric Feldmeier\\\nChristoph Frädrich\\\nGordon Fraser\\\nSophia Geserer\\\nKatharina Götz\\\nEva Gründinger\\\nNina Körber\\\nMarvin Kreis\\\nSebastian Schweikl\\\nAndreas Stahlbauer\\\nEmma Wang\\\nPhil Werli\\\nNik Zantner\n\n\nWhisker is supported by the project FR 2955/3-1 funded by the\n\"Deutsche Forschungsgemeinschaft\".\n\n## References\n\n```\n@inproceedings{DBLP:conf/sigsoft/StahlbauerKF19,\n  author    = {Andreas Stahlbauer and\n               Marvin Kreis and\n               Gordon Fraser},\n  title     = {Testing scratch programs automatically},\n  booktitle = {{ESEC/SIGSOFT} {FSE}},\n  pages     = {165--175},\n  publisher = {{ACM}},\n  year      = {2019}\n}\n```\n\n```\n@inproceedings{DBLP:conf/ssbse/DeinerFFGZ20,\n  author    = {Adina Deiner and Christoph Fr{\\\"{a}}drich and\n               Gordon Fraser and Sophia Geserer and\n               Niklas Zantner},\n  title     = {Search-Based Testing for Scratch Programs},\n  booktitle = {12th International Symposium on Search-Based Software Engineering},\n  series    = {Lecture Notes in Computer Science},\n  volume    = {12420},\n  pages     = {58--72},\n  publisher = {Springer},\n  year      = {2020},\n}\n```\n\n```\n@InProceedings{gotz2022model,\n  title \t\t= {Model-based Testing of Scratch Programs},\n  author \t\t= {G{\\\"o}tz, Katharina and Feldmeier, Patric and Fraser, Gordon},\n  booktitle \t= {Proceedings of the International Conference on Software Testing, Verification and Validation (ICST'22)},\n  pages \t\t= {411--421},\n  year \t\t\t= {2022},\n  publsiher     = {IEEE},\n  doi \t\t\t= {10.1109/ICST53961.2022.00047}\n}\n```\n\n```\n@misc{deiner2022automated,\n      title         = {Automated Test Generation for Scratch Programs},\n      author        = {Adina Deiner and Patric Feldmeier and Gordon Fraser and Sebastian Schweikl and Wengran Wang},\n      year          = {2022},\n      eprint        = {2202.06274},\n      archivePrefix = {arXiv},\n      primaryClass  = {cs.SE}\n}\n```\n\n```\n@InProceedings{feldmeier2022neuroevolution,\n\tauthor \t\t= {Feldmeier, Patric and Fraser, Gordon},\n\tbooktitle \t= {Proceedings of the International Conference on Automated Software Engineering (ASE'22)},\n\tpublisher \t= {ACM},\n\ttitle \t\t= {Neuroevolution-Based Generation of Tests and Oracles for Games},\n\tyear \t\t= {2023},\n\tdoi \t\t= {10.1145/3551349.3556939},\n\tpages \t\t= {1--13}\n}\n```\n\n```\n@article{feldmeier2023learning,\n  title         = {Learning by Viewing: Generating Test Inputs for Games by Integrating Human Gameplay Traces in Neuroevolution},\n  author        = {Feldmeier, Patric and Fraser, Gordon},\n  journal       = {arXiv preprint arXiv:2304.06413},\n  year          = {2023},\n  doi           = {10.48550/arXiv.2304.06413}\n}\n```\n\n```\n@inproceedings{nuzzlebug24,\n  author    = {Adina Deiner and Gordon Fraser},\n  title     = {NuzzleBug: Debugging Block-Based Programs in Scratch },\n  booktitle = {ACM/IEEE International Conference on Software Engineering (ICSE)},\n  publisher = {{IEEE}},\n  year      = {2024}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fse2p%2Fwhisker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fse2p%2Fwhisker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fse2p%2Fwhisker/lists"}