{"id":14989750,"url":"https://github.com/ethaks/fvtt-quench","last_synced_at":"2025-04-12T00:32:06.918Z","repository":{"id":36968735,"uuid":"413784922","full_name":"Ethaks/FVTT-Quench","owner":"Ethaks","description":"Harden your Foundry module or system code with end-to-end UI tests directly within Foundry. Powered by Mocha and Chai.","archived":false,"fork":false,"pushed_at":"2024-04-23T06:41:43.000Z","size":6139,"stargazers_count":23,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-23T11:12:50.523Z","etag":null,"topics":["chai","fast-check","foundry-vtt","foundryvtt","mocha","testing"],"latest_commit_sha":null,"homepage":"https://ethaks.github.io/FVTT-Quench/index.html","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/Ethaks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"ethaks","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2021-10-05T11:14:26.000Z","updated_at":"2024-04-24T13:58:50.294Z","dependencies_parsed_at":"2023-10-18T22:22:00.856Z","dependency_job_id":"2811b744-4b63-4898-baf0-171a45097076","html_url":"https://github.com/Ethaks/FVTT-Quench","commit_stats":{"total_commits":366,"total_committers":6,"mean_commits":61.0,"dds":0.5191256830601093,"last_synced_commit":"53cd94faad2113a694c389b8b9d1f3ea69e544d7"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethaks%2FFVTT-Quench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethaks%2FFVTT-Quench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethaks%2FFVTT-Quench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ethaks%2FFVTT-Quench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ethaks","download_url":"https://codeload.github.com/Ethaks/FVTT-Quench/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223486881,"owners_count":17153241,"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":["chai","fast-check","foundry-vtt","foundryvtt","mocha","testing"],"created_at":"2024-09-24T14:18:51.832Z","updated_at":"2024-11-07T09:03:39.007Z","avatar_url":"https://github.com/Ethaks.png","language":"TypeScript","funding_links":["https://ko-fi.com/ethaks"],"categories":[],"sub_categories":[],"readme":"\u003ch1 style=\"text-align: center\" align=\"center\"\u003e\n    \u003cimg alt=\"Quench Logo\" src=\"media/quench-logo.webp\" width=256 height=256\u003e\n  \u003cbr\u003e\n  Quench\n\u003c/h1\u003e\n\n\u003cp style=\"text-align: center\" align=\"center\"\u003e\n  \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/Ethaks/FVTT-Quench/check.yml?branch=master\"\u003e\n  \u003ca href=\"https://github.com/Ethaks/FVTT-Quench/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/downloads/Ethaks/FVTT-Quench/latest/module.zip\" alt=\"Downloads\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://forge-vtt.com/bazaar#package=quench\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/dynamic/json?label=Forge%20Installs\u0026query=package.installs\u0026suffix=%25\u0026url=https%3A%2F%2Fforge-vtt.com%2Fapi%2Fbazaar%2Fpackage%2Fquench\u0026colorB=4aa94a\" alt=\"Forge Install %\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@ethaks/fvtt-quench\"\u003e\n    \u003cimg alt=\"npm (scoped)\" src=\"https://img.shields.io/npm/v/@ethaks/fvtt-quench?color=g\u0026logo=npm\"\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003ca href=\"https://www.foundryvtt-hub.com/package/quench/\"\u003e\n    \u003cimg src=\"https://img.shields.io/endpoint?logoColor=white\u0026url=https%3A%2F%2Fwww.foundryvtt-hub.com%2Fwp-json%2Fhubapi%2Fv1%2Fpackage%2Fquench%2Fshield%2Fendorsements\" alt=\"Foundry Hub Endorsements\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/endpoint?url=https://foundryshields.com/version?url=https://github.com/Ethaks/FVTT-Quench/releases/latest/download/module.json\" alt=\"Supported Foundry Versions\" /\u003e\n\u003c/p\u003e\n\nHarden your Foundry module or system code with end-to-end UI tests directly within Foundry.\nPowered by [Mocha](https://mochajs.org/) and also includes [Chai](https://www.chaijs.com/) and [fast-check](https://github.com/dubzzz/fast-check).\n\nQuench adds a test runner UI as a native Foundry `Application`.\nYou can register test suites with quench and view them in the test runner, then run them and view the results.\nAdditional API documentation can be found [here](https://ethaks.github.io/FVTT-Quench/index.html).\n\n![Example Tests](media/example-tests.webp)\n\n## Usage\n\nThe primary public API is the `Quench` class.\nA global instance of `Quench` is available as a global called `quench`, guaranteed to be initialized after the core `\"init\"` hook.\nThis class includes references to both the mocha and chai globals, as well as some methods to add new test batches and run the tests.\n\nQuench uses \"test batches\" as another layer of organization above the built-in mocha suites and tests.\nTest batches are at the top layer of the hierarchy, can contain suites and/or tests, and can be enabled or disabled through the Quench UI.\nEnabling or disabling batches allows you to pick and choose only a subset of suites and tests to execute in one test run.\n\n### `quenchReady` Hook\n\nQuench provides a `\"quenchReady\"` hook, which indicates when Quench is ready for you to start registering batches.\n`\"quenchReady\"` is guaranteed to occur after the core `\"init\"` hook, as it is fired in Quench's `\"setup\"` hook.\n`\"quenchReady\"` receives the current `Quench` instance as an argument.\n\n### `quenchReports` Hook\n\nIn addition to the results displayed in the app, Quench provides a `\"quenchReports\"` hook.\nIt is fired when a batch run is finished, and receives an object with the following properties as argument:\n\n- `json`: A string containing a JSON report as generated by Mocha.\n\n### Register a test batch\n\nYou can register a Quench test batch to be executed with Quench by calling `quench.registerBatch`.\n`registerBatch` takes the following arguments:\n\n- `key` – a unique batch key that identifies this test batch.\n  If multiple test batches are registered with the same key, the latest registration will overwrite previous registrations.\n- `registrationFunction` – this function will be executed to register the suites and tests within this batch.\n  It takes a `context` argument, which contains the following functions necessary for defining a suite of tests:\n  - Mocha – `describe`, `it`, `after`, `afterEach`, `before`, `beforeEach`, and `utils`.\n  - Chai – `assert`, `expect`, and `should`. `should` is also made available by it extending `Object.prototype`.\n  - fast-check – `fc`.\n- `options` -\n  - `displayName` – the name for this batch that will be shown in the UI and in the detailed test results.\n    This is optional, Quench will fall back to the batch key if omitted.\n  - `snapBaseDir` – the directory from which snapshots for this batch will be read, and where snapshots will be stored.\n    This is optional, Quench will fall back to `Data/__snapshots__/\u003cpackage name\u003e/`, with each batch having its own directory there.\n  - `preSelected` – whether this batch will appear as checked when added to the UI.\n    This is optional, Quench will fall back to `true`.\n\nExample:\n\n```javascript\nHooks.on(\"quenchReady\", (quench) =\u003e {\n  quench.registerBatch(\n    \"quench.examples.basic-pass\",\n    (context) =\u003e {\n      const { describe, it, assert } = context;\n\n      describe(\"Passing Suite\", function () {\n        it(\"Passing Test\", function () {\n          assert.ok(true);\n        });\n      });\n    },\n    { displayName: \"QUENCH: Basic Passing Test\" },\n  );\n});\n```\n\nAdditional examples can be found in this repository's [`nonsense-tests.ts` file](./src/module/quench-tests/nonsense-tests.ts)\n\n### Run test batches using the API\n\nIn addition to starting batch runs through the UI, Quench provides a method to run batches directly.\nThis method is available through `quench.runBatches`.\nAdditional information can be found in the [API documentation](https://ethaks.github.io/FVTT-Quench/index.html).\n\n```javascript\n// Run all batches\nquench.runBatches(\"**\");\n\n// Run a single batch and upload the JSON report to Foundry's server at `Data/quench-report.json`\nquench.runBatches([\"quench.examples.basic-pass\"], { json: true });\n```\n\n### Snapshots\n\n**Snapshot handling is currently in alpha! The current API is not final and subject to change – all input is welcome!**\n\nQuench supports snapshot testing, allowing for Chai's comparisons to work with data previously serialised using [pretty-format](https://www.npmjs.com/package/pretty-format) – this includes support for regular JS objects, as well as e.g. DOM elements.\nTo compare an object to a snapshot, you can use `matchSnapshot()` as assertion.\n\nIf a test run includes failed tests using snapshots, Quench will show a button in its UI that allows to update the snapshots of those tests.\nAlternatively, setting `quench.snapshots.enableUpdates = true` will pass all snapshot tests and store the actual value as new expected value, updating all files belonging to tests where the actual value did not match the expected one.\n\nBy default, each batch using snapshots gets its own directory in which each snapshot is stored in a `.snap.txt` file whose name is generated by hashing the test's full title.\nThe base directory in which each batch's directory is created is `Data/__snapshots__/\u003cpackage name\u003e`.\nWhen registering a batch, that batch's base directory can be overwritten by providing a `snapBaseDir` option; the path is resolved using Foundry's `Data` directory as root.\n\nExample:\n\n```javascript\nquench.registerBatch(\n  \"quench.examples.snapshot-test\",\n  (context) =\u003e {\n    const { describe, it, assert, expect } = context;\n\n    describe(\"Snapshot Tests\", function () {\n      it(\"Uses assert to match against a snapshot\", function () {\n        assert.matchSnapshot({ foo: \"bar\" });\n      });\n\n      it(\"Uses expect to match against a snapshot\", function () {\n        expect({ foo: \"baz\" }).to.matchSnapshot();\n      });\n    });\n  },\n  { displayName: \"QUENCH: Snapshot Test\", snapBaseDir: \"__snapshots__/quench-with-a-twist\" },\n);\n```\n\n### Typescript\n\nQuench offers a package on npm containing its types, allowing Typescript to check for correct API usage and provide autocompletion.\nThe package can be installed with\n\n```bash\nnpm install --save-dev @ethaks/fvtt-quench\n```\n\nThe types can then be used by adding them to the `types` section of your `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"@ethaks/fvtt-quench\"]\n  }\n}\n```\n\nBy default, the `quench` global is typed as `Quench | undefined`.\nTo access it, you have to use a type guard or explicitly type it as initialized and present by adding a `quench` property to the global `LenientGlobalVariableTypes` interface (see [foundry-vtt-type's FAQ](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki/FAQ#why-cant-i-access-any-properties-on-game--canvas))\n\n### Conventions\n\nBy convention, batch keys should begin with the package short name, followed by a period and then a simple identifier for the batch.\nBatch display names should begin with the package name in caps, followed by a colon, and a short description of the tests included in the batch.\n\nKey: `\u003cpackage\u003e.batch.identifier`  \nDisplay name: `\u003cPACKAGE\u003e: A description of the batch's contents`\n\n## License\n\nLicensed under the GPLv3 License (see [LICENSE](LICENSE)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethaks%2Ffvtt-quench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethaks%2Ffvtt-quench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethaks%2Ffvtt-quench/lists"}