Contributing

What good contributions look like

Contributions are welcome, and the bar is about focus, not size. A small change with a clear problem statement beats a large rewrite every time. Before writing code for anything non-trivial, open an issue describing the problem, it protects your time as much as the maintainer’s.

Prerequisites: Node.js 18 or later, and all changes must pass the existing test suite.

The workflow

1. Fork the repository and create a branch from master.
2. Name the branch feat/<short-description>, fix/<short-description>, or chore/<short-description>.
3. Make your changes. Do not introduce new dependencies without prior discussion, the project is deliberately light.
4. Run the test suite and confirm everything passes.
5. Open a pull request against master with a clear description of what changed and why.

git checkout -b fix/clearer-locator-error
# ...make the change...
node --test tests/
git commit -m "fix: explain ambiguous locator matches in the error"
git push origin fix/clearer-locator-error

A typical fix branch from clone to PR.

Code standards

• Plain JavaScript (CommonJS modules), compatible with Node.js 18. No transpilation, no build step.
• New modules must have a single, clearly named responsibility, mirroring the layered design described in Architecture.
• Prefer explicit, readable code over clever abstractions.
• Tests for new behavior are expected unless the change is purely cosmetic.

Writing a bug report that gets fixed

The difference between a report that gets fixed this week and one that goes stale is reproducibility. Include:

• OrbitTest version, Node version, and operating system.
• Browser details for web issues; device model and Android version for mobile issues.
• Steps to reproduce, ideally a minimal test file that shows the problem.
• Expected behavior versus actual behavior.
• Relevant report artifacts: the error output, a screenshot, a trace. orbittest doctor output helps for environment-shaped problems.

Security issues: report privately

Security vulnerabilities are the one category that must not go through public issues. A public report puts every user at risk before a fix exists. Instead, open a private security advisory on GitHub or contact the maintainer directly, details get handled responsibly, fixed, and disclosed once users can update.

Licensing and trademarks

OrbitTest is created and maintained by Abhay and licensed under the Apache License 2.0. Forks and modified versions are permitted, but must preserve copyright, license, and notice attribution, and must not imply affiliation with the official project. The OrbitTest name, logo, and branding are governed by the project’s TRADEMARKS.md. Orbittest Studio is distributed under the MIT License, with license and attribution notices for bundled third-party components included in the installer.

Frequently asked questions

Can I contribute documentation instead of code?

Yes, documentation fixes are real contributions and follow the same PR workflow. Unclear docs are bugs.

My PR mixes a bug fix with a small refactor. Is that OK?

Split it. Two small PRs review faster than one mixed PR, and the fix is not held hostage to discussion about the refactor.

Can I build a commercial product on OrbitTest?

The Apache 2.0 license allows commercial use, modification, and redistribution, with attribution preserved and without implying official affiliation. Check TRADEMARKS.md before using the name or logo.

Related pages

• Architecture — The seven internal modules, how a click travels from your test to the browser, and how the Android stack swaps in.
• Roadmap — Current status and direction: browser diagnostics, mobile and Studio plans, API testing, and what is deliberately not planned.
• Installer Integrity — Verify the Studio installer with its published SHA256 hash before running it, and follow safe download practices.
• Introduction — What OrbitTest is, the intent-first testing idea behind it, and how the framework and Orbittest Studio fit together.