{"id":21280465,"url":"https://github.com/terrablue/debris","last_synced_at":"2026-01-01T22:04:28.475Z","repository":{"id":65562200,"uuid":"475839946","full_name":"terrablue/debris","owner":"terrablue","description":"JavaScript testing framework with support for fixtures, asynchronicity and spaced testing","archived":false,"fork":false,"pushed_at":"2023-09-17T10:46:46.000Z","size":78,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-19T13:46:29.902Z","etag":null,"topics":["javascript","nodejs","testing","testing-framework"],"latest_commit_sha":null,"homepage":"https://npmjs.com/debris","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terrablue.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,"publiccode":null,"codemeta":null}},"created_at":"2022-03-30T11:04:34.000Z","updated_at":"2023-03-15T14:00:05.000Z","dependencies_parsed_at":"2024-11-21T10:30:24.905Z","dependency_job_id":"6cf0410d-e818-4859-b50c-04a19d30c701","html_url":"https://github.com/terrablue/debris","commit_stats":{"total_commits":57,"total_committers":1,"mean_commits":57.0,"dds":0.0,"last_synced_commit":"458f418f0bee94dc05a066f66c5afe1d274c98dc"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrablue%2Fdebris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrablue%2Fdebris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrablue%2Fdebris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terrablue%2Fdebris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terrablue","download_url":"https://codeload.github.com/terrablue/debris/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243738985,"owners_count":20340002,"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":["javascript","nodejs","testing","testing-framework"],"created_at":"2024-11-21T10:30:19.092Z","updated_at":"2026-01-01T22:04:28.404Z","avatar_url":"https://github.com/terrablue.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debris: A JavaScript Testing Framework\n\nDebris is a JavaScript testing framework with support for fixtures,\nasynchronicity and spaced testing.\n\n## Features\n\n* No dependencies\\*\n* Descriptive\n* Fixtures\n* Promise support\n* Test spacing (metatesting, fuzzy testing)\n* Snapshots\n* Individual test running\n\n\\* aside from `runtime-compat`, which reflects [Flog's standard library][flog].\n\n## Configuring\n\n*Skip this part if you don't need a custom configuration.*\n\nIn your project root create a `debris.json`.\n\n```json\n{\n  \"fixtures\": \"fixtures\",\n  \"explicit\": true\n}\n```\n\n`fixtures` is the directory containing your test fixtures, the path is relative\nto your project root.\n\nIf you're interested in hidding passed tests change `explicit` to `false`.\n\n## Writing tests\n\nIf you're testing `src/truth.js`, create a `src/truth.spec.js` file.\n\n```js\nexport default test =\u003e {\n  test.case(\"there is only *the* truth\", assert =\u003e {\n    assert(true).equals(true);\n  });\n});\n```\n\nRun the test.\n\n```\nnpx debris\n```\n\n### Adding fixtures\n\nFixtures represent a state of your application that you don't want to\nmanually set each time.\n\nCreate a fixture file in the fixtures directory, `truth.js`\n(`fixtures/truth.js`).\n\n```js\nexport default () =\u003e true;\n```\n\nFixtures are made available to all test cases as the second parameter to the\n`case` method of `test`.\n\nModify your test.\n\n```js\nexport default test =\u003e {\n  test.case(\"there is only *the* truth\", (assert, fixtures) =\u003e {\n    assert(fixtures.truth).equals(true);\n  });\n}\n```\n\nThe properties of `fixtures` reflect the filenames (without `.js`) of the\nfixtures you created. You can thus also destructure to pull in the fixtures you\nneed for an individual case.\n\n```js\nexport default test =\u003e {\n  test.case(\"there is only *the* truth\", (assert, {truth}) =\u003e {\n    assert(truth).equals(true);\n  });\n}\n```\n\n### Transformed fixtures\n\nSometimes you need all the cases of a test to do something common that isn't\nnecessarily achievable with fixtures. For example you might want to read a file\nbased on a test's name and then make sure it fulfills certain criteria.\n\nYou can call the `refix` method of the `test` parameter to achieve that.\n\n```js\nexport default test =\u003e {\n  test.refix(async (fixtures, {description}) =\u003e {\n    const path = description.replaceAll(\" \", \"-\") + \".html\";\n    // assume the function `read` returns a file's contents at `path`\n    const contents = await read(path);\n    return {...fixtures, contents};\n  }));\n\n  test.case(\"file containing the truth\", (assert, {contents}) =\u003e {\n    assert(contents).equals(\"true\");\n  });\n}\n```\n\nThe first of argument of `refix` is a mapper that takes the original `fixtures`\nparameter and the case itself as parameters and maps it to a (modified) fixtures\nobject which is available to the case.\n\n### Case spacing / fuzzing\n\nSometimes you don't want individual cases with set input but the same case\nexecuted many times with different inputs. You can use the `space` method of\n`test` for that.\n\n```js\nexport default test =\u003e {\n  test.space(\"there is only *the* truth\", [true, false], (assert, each) =\u003e {\n    assert(each).equals(true);\n  });\n}\n```\n\nThis effectively creates two cases with the same definition and different input,\none which will pass and another which will fail.\n\nSpacing can be combined with fixtures, see API later on.\n\n### Snapshots\n\nSnapshots are dynamically generated fixtures. With snapshots you can test the\nstability of a given object using `assert(...).stable()`.\n\nOn the first run, the asserted value is JSON-stringified and saved to disk at\nthe same location as the test itself. On a subsequent run, the asserted value\nis compared to the value on disk. For these kind of tests to be effective you\nshould commit the dynamically generated fixtures alongside your test.\n\n### Running tests individually\n\nIf you're working on a test and aren't interested in others you can run it\nindividually and ignore the rest. Just use the test's generated id.\n\nThis runs only the first test.\n\n```\nnpx debris 0.0.0\n```\n\n### Test-driven development\n\nIf you're doing TDD and want tests to explicitly fail as you write them you\ncan use `assert.fail()`. Calling it is equivalent to writing\n`assert(true).false()`.\n\n## API\n\nSubject to breakage until v1.\n\n### `Test` (the parameter `test` passed to a spec)\n\n#### `case(String description, Function body)`\n\nDefines a case using the given `description`. `body` will be executed with\n`assert` as its first and `fixtures` as its second parameter.\n\n#### `for(Array fixtures, Case case)`\n\nExecutes once per test case, transforming `fixtures`. The return value will be\ninput to the case.\n\nThe default implementation unless overwritten is an identity function on\n`fixtures` (`fixtures =\u003e fixtures`).\n\n**This function should not be called but overwritten.**\n\n#### `space(String description, Array inputs, Function body)`\n\nDefines a case space using the given `description` and `inputs`. `body` will be\nexecuted `inputs.length` times with the respective input from `inputs` as its\nfirst parameter and `fixtures` as its second. `body` will be signed in as\n`Test.prototype.case`.\n\n## Roadmap to v1\n\n* 100% self-coverage\n* Sane configuration defaults\n* Proper logger (stdio, file)\n* Documentation\n\n## License\n\nMIT\n\n[flog]: https://github.com/flogjs/std\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrablue%2Fdebris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterrablue%2Fdebris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterrablue%2Fdebris/lists"}