TDD Workflow

GJSify welcomes contributions! This page describes how we port new Node.js or Web APIs to GJS. It is a strict test-driven workflow that keeps both Node.js and GJS implementations honest.

If you have not set up the monorepo yet, start with Development Setup.

TDD workflow

GJSify follows a test-driven development approach:

1. Study the API: read refs/node/lib/<name>.js for the canonical Node.js implementation (or the relevant refs/deno/ext/… file for Web APIs)
2. Port tests: write tests in *.spec.ts using @gjsify/unit
3. Verify on Node.js: gjsify run test:node (in the package). Tests should pass against the real Node.js implementation first
4. Test on GJS: gjsify run test:gjs, and expect failures, then fix the GJSify implementation
5. Implement: use @girs/* types, consult refs/{deno,bun,quickjs,workerd}/ for reference
6. Iterate: until both platforms pass

Testing rules

• Tests must pass on both Node.js and GJS
• Never weaken tests to accommodate GJS limitations. Fix the implementation instead
• Web API packages have a third test axis: tests/browser/ runs their test.browser.mts bundles under Playwright (Firefox, the same SpiderMonkey engine as GJS) to verify our implementation claims against the real browser platform
• Use the node: prefix for all Node.js imports in tests
• Use @gjsify/unit as the test framework; shared matchers: toBe, toEqual, toBeTruthy, toBeFalsy, toContain, toMatch, toThrow
• Platform-specific test logic belongs in a separate *.gjs.spec.ts file or inside an on('Gjs', …) block, not sprinkled through the shared spec

Full validation

Before opening a pull request, run the full validation sequence:

Terminal

gjs -m install.mjs                 # published gjsify, SHA-256 verified
gjsify install --immutable
gjsify run build:infra             # produces the CLI the next line uses
PATH="$PWD/node_modules/.bin:$PATH"
gjsify run clear && gjsify run build && gjsify run check && gjsify run test

This mirrors what CI does and catches most integration issues before review.

Where to start

• Browse the Packages Overview for modules that are still Partial or Stub
• Check open issues on GitHub
• Improve documentation: this very site is in website/src/content/docs/