Skip to main content
We welcome contributions to Universal Speedtest CLI! Whether you’re fixing bugs, adding features, improving documentation, or proposing new providers, your help is appreciated.

​
Ways to Contribute

Report Issues

Found a bug or have a feature request? Open an issue on GitHub.

Submit Code

Fix bugs, add features, or improve existing functionality with pull requests.

Improve Documentation

Help make our docs clearer and more comprehensive.

Propose Providers

Suggest new speed test provider integrations.

​
Development Setup

1

Clone the repository

git clone https://github.com/hsblabs/universal-speedtest-cli.git
cd universal-speedtest-cli
2

Ensure Go is installed

Universal Speedtest CLI requires Go 1.21 or higher.
go version
3

Build from source

For detailed build instructions, see the Building from Source guide.
go build -trimpath -ldflags="-s -w" -o dist/unispeedtest ./cmd/unispeedtest
4

Run tests

Ensure all tests pass before submitting changes:
go test ./...

​
Running Tests

Our test suite covers core functionality, statistics calculations, and provider integrations.

​
Run all tests

go test ./...

​
Run tests with verbose output

go test -v ./...

​
Run tests for a specific package

go test ./internal/stats
go test ./internal/cloudflare

​
Run tests with coverage

go test -cover ./...
When adding new features, please include appropriate test coverage. We maintain tests in:
  • internal/stats/stats_test.go - Statistics calculations
  • internal/cloudflare/measure_test.go - Cloudflare provider
  • internal/reporter/quality_test.go - Quality reporting

​
Submitting Changes

1

Create a feature branch

git checkout -b feature/your-feature-name
2

Make your changes

  • Write clear, concise code
  • Follow existing code style and conventions
  • Add tests for new functionality
  • Update documentation as needed
3

Run tests and verify

go test ./...
go build -o dist/unispeedtest ./cmd/unispeedtest
./dist/unispeedtest
4

Commit and push

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name
5

Open a pull request

  • Describe what your PR does and why
  • Reference any related issues
  • Ensure CI checks pass
  • Be responsive to review feedback

​
Code Style and Conventions

​
Go Code Standards

  • Follow standard Go formatting: go fmt ./...
  • Run go vet ./... to catch common issues
  • Use meaningful variable and function names
  • Add comments for exported functions and complex logic
  • Keep functions focused and concise

​
Commit Messages

Use conventional commit format:
  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • test: for test additions or changes
  • refactor: for code refactoring
  • chore: for maintenance tasks
Example: 
feat: add timeout flag for unstable networks

Adds --timeout flag to allow users to configure request timeouts
for networks with high latency or packet loss.

Fixes #123

​
Testing Guidelines

  • Write table-driven tests when testing multiple cases
  • Use descriptive test names that explain what’s being tested
  • Test edge cases and error conditions
  • Mock external dependencies when appropriate
  • Aim for high coverage of critical paths

​
Feature Priorities

When deciding what to work on, refer to our Roadmap for current priorities:
  1. Phase 1: Foundation hardening (error handling, reliability)
  2. Phase 2: Multi-provider support (extensibility)
  3. Phase 3: CLI enhancements (output formats, profiles)
  4. Phase 4: Ecosystem integration (packaging, distribution)
Features that improve stability, maintain backward compatibility, and enhance automation workflows are highly valued.

​
Reporting Issues

When reporting bugs or requesting features:
Description
Clear description of the issueSteps to Reproduce
  1. Run command: unispeedtest -json
  2. Observe error
Expected Behavior
What should happenActual Behavior
What actually happensEnvironment
  • OS: Linux/macOS/Windows
  • Go version: 1.21
  • CLI version: 1.0.0
Additional Context
Any other relevant information
Problem
Describe the use case or problem you’re trying to solveProposed Solution
Your suggested approachAlternatives Considered
Other options you’ve thought aboutAdditional Context
Examples, references, or mockups

​
Questions and Support

Need Help?

Thank you for contributing! Every contribution, no matter how small, helps make Universal Speedtest CLI better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us