|
| 1 | +# HTMX Testing Guide |
| 2 | + |
| 3 | +This guide outlines how to test htmx, focusing on running tests headlessly or in a browser environment, running individual tests, and other testing concerns. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +1. Ensure you have a currently supported Node.js and npm installed. |
| 8 | +2. Install dependencies by running: |
| 9 | + ```bash |
| 10 | + npm install |
| 11 | + npm run test |
| 12 | + ``` |
| 13 | +During test runs it will auto install playwright |
| 14 | + |
| 15 | +## Running All Tests |
| 16 | + |
| 17 | +To run all tests in headless mode, execute: |
| 18 | +```bash |
| 19 | +npm test |
| 20 | +``` |
| 21 | +This will run all the tests using headless Chrome. |
| 22 | + |
| 23 | +To run all tests against all browsers in headless mode, execute: |
| 24 | +```bash |
| 25 | +npm run test:all |
| 26 | +``` |
| 27 | +This will run the tests using Playwright’s headless browser setup across Chrome, Firefox, and WebKit (Safari-adjacent). |
| 28 | + |
| 29 | +To run all tests against a specific browser, execute: |
| 30 | +```bash |
| 31 | +npm run test:chrome |
| 32 | +npm run test:firefox |
| 33 | +npm run test:webkit |
| 34 | +``` |
| 35 | + |
| 36 | +## Running Individual Tests |
| 37 | + |
| 38 | +### Headless Mode |
| 39 | +To run a specific test file headlessly, for example `test/core/ajax.js`, use the following command: |
| 40 | +```bash |
| 41 | +npm test test/core/ajax.js |
| 42 | +``` |
| 43 | +If you want to run only one specific test, you can temporarily change `it("...` to `it.only("...` in the test file, and then specify the test file as above. Don't forget to undo this before you commit! You will get eslint warnings now to let you know when you have temporary `.only` in place to help avoid commiting these. |
| 44 | + |
| 45 | +### Browser Mode |
| 46 | +To run tests directly in the browser, simply `open test/index.html` in a browser. |
| 47 | +On Ubuntu you can run: |
| 48 | + |
| 49 | +```bash |
| 50 | +xdg-open test/index.html |
| 51 | +``` |
| 52 | +This runs all the tests in the browser using Mocha instead of web-test-runner for easier and faster debugging. |
| 53 | + |
| 54 | +From the Mocha browser view you can rerun a just a single test file by clicking the header name or you can click on the play icon to re-play a single test. This makes it easy to update this test/code and refresh to re-run this single test. The browser console also now logs the names of the running tests so you can check here to find any errors or logs produced during each test execution. Adding debugger statements in your code or breakpoints in the browser lets you step though the test execution. |
| 55 | + |
| 56 | +If you really want to open web-test-runner in headed mode, you can run: |
| 57 | +```bash |
| 58 | +npm run test:debug |
| 59 | +``` |
| 60 | +This will start the server, and open the test runner in a browser. From there you can choose a test file to run. Note that all test logs will show up only in dev tools console unlike Mocha. |
| 61 | + |
| 62 | +## Code Coverage Report |
| 63 | +Lines of code coverage reporting will only work when running the default chrome headless testing |
| 64 | + |
| 65 | +After a test run completes, you can open `coverage/lcov-report/index.html` to view the code coverage report. On Ubuntu you can run: |
| 66 | +```bash |
| 67 | +xdg-open coverage/lcov-report/index.html |
| 68 | +``` |
| 69 | + |
| 70 | +## Test Locations |
| 71 | +- All tests are located in the `test/attribues` and `test/core` directories. Only .js files in these directory will be discovered by the test runner. |
| 72 | +- The `web-test-runner.config.mjs` file in the root directory contains the boilerplate HTML for the test runs, including `<script>` tags for the test dependencies. |
| 73 | + |
| 74 | +### Local CI prediction |
| 75 | +You can run `npm run test:ci` to locally simulate the result of the CI run. This is useful to run before pushing to GitHub to avoid fixup commits and CI reruns. |
0 commit comments