{"id":16641794,"url":"https://github.com/samthor/headless-test","last_synced_at":"2025-12-24T10:46:29.619Z","repository":{"id":40841023,"uuid":"252110519","full_name":"samthor/headless-test","owner":"samthor","description":"Run Mocha tests in a headless browser","archived":false,"fork":false,"pushed_at":"2022-06-23T02:33:59.000Z","size":288,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-21T05:34:37.071Z","etag":null,"topics":["http","mocha","puppeteer","test"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samthor.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}},"created_at":"2020-04-01T08:02:14.000Z","updated_at":"2020-04-22T03:46:01.000Z","dependencies_parsed_at":"2022-09-17T21:11:02.925Z","dependency_job_id":null,"html_url":"https://github.com/samthor/headless-test","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fheadless-test","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fheadless-test/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fheadless-test/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samthor%2Fheadless-test/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samthor","download_url":"https://codeload.github.com/samthor/headless-test/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243164811,"owners_count":20246718,"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":["http","mocha","puppeteer","test"],"created_at":"2024-10-12T07:47:53.115Z","updated_at":"2025-12-24T10:46:29.591Z","avatar_url":"https://github.com/samthor.png","language":"JavaScript","readme":"[![Tests](https://github.com/samthor/headless-test/workflows/Tests/badge.svg)](https://github.com/samthor/headless-test/actions)\n\n\nRuns tests in a headless browser (Chrome-only via Puppeteer for now).\nUseful to test Web Components, polyfills, or anything else that needs real browser APIs.\n\nUses [Mocha](https://npmjs.com/package/mocha) and provides the [Chai](https://npmjs.com/package/chai) assertion library.\n\n# Usage\n\nInstall `headless-test` via your favourite package manager.\n\n## Command-Line or CI\n\nRun and pass a number of files (including tests) which will be loaded in-order as ESM:\n\n```bash\nheadless-test your-code.js your-tests.js\n```\n\nThis will exit with non-zero if the Mocha tests fail.\nEasy!\n\nNote that `your-tests.js` should look like a totally normal Mocha test file:\n\n```js\n// no imports required for Mocha or Chai, they'll be available globally\nsuite('check stuff', () =\u003e {\n  test('does a thing', async () =\u003e {\n    // ...\n    await 'foo';\n    assert(true, 'this passes');\n  });\n});\n```\n\nYou can also specifiy `-b` to switch Mocha to BDD mode, or see `--help` for other options.\n\nThis works by hosting a webserver in the current directory (with [dhost](https://npmjs.com/package/dhost)) so you can load other dependencies.\n\n### Extras\n\nCSS can also be included in the page for tests.\nFor example:\n\n```bash\nheadless-test your-code.js your-css.css your-tests.js\n```\n\n## API\n\nYou can also use `headless-test` programatically.\nThe most common use case is to pass a URL (e.g., if you're already running a dev server) and specify `load` to load specific resources as ESM into the test environment.\n\n```js\nconst headlessTest = require('headless-test');\n\nconst p = headlessTest('http://localhost:8080', {\n  load: ['your-code.js', 'your-tests.js'],\n  driver: {\n    // options passed to `mocha.setup`\n    ui: 'tdd',\n  },\n});\n\np.then(() =\u003e /* something */);\n```\n\nInstead of passing a URL, you can also pass a `http.Server` to read its URL (e.g., if you're running a dev server in the same process).\n\n### Virtual Resources\n\nYou can also specify _virtual_ script files, if your tests aren't able to be found on your local web server.\nThey'll still be run in the same origin, but won't be able to `import` each other.\nFor example:\n\n```js\nconst p = headlessTest('http://localhost:1234', {\n  load: [\n    {code: 'console.info(\"hello\"); suite(\"tests\", () =\u003e { /* stuff */ });'},\n    {code: testCode},\n  ],\n});\n```\n\nIf you're not loading any real script files, it's valid to pass `null` for the URL.\n\n## Notes\n\nDon't use this for integration tests.\nYou should be running Mocha locally for that, and having it start Puppeteer to click on things.\n\n## Dependencies\n\nThis package has a few direct dependencies, although _those_ dependencies have a huge number of transitive dependencies.\nHere's the short list:\n\n* `mocha` is the default test driver\n* `chai` provides an assertion library to your tests\n* `puppeteer` includes headless Chromium\n\nIncluded for the CLI only:\n\n* `dhost` provides a never-caching static web server for files\n* `mri` parses command-line arguments\n* `chalk` to make things pretty, because it's included by transitive deps anyway ¯‍\\‍_‍(‍ツ‍)‍_‍/‍¯\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fheadless-test","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamthor%2Fheadless-test","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamthor%2Fheadless-test/lists"}