AGENTS.md · grafana/k6

Sections

1. Project Overview
2. Common Development Commands
3. Architecture Overview
4. Testing Structure
5. Important Configuration Files
6. Development Guidelines
7. Git Workflow and Branching Strategy
8. Common File Locations

First lines (shown under the repo's AGPL-3.0 license)

## Project Overview

k6 is a modern load testing tool built in Go. It allows developers to write JavaScript test scripts to simulate user behavior and measure system performance. The tool features configurable load generation, multiple protocol support (HTTP, WebSockets, gRPC, Browser), and flexible metrics output.

## Common Development Commands

### Building and Testing
```bash
# Build the k6 binary
make build
# or
go build

# Run all tests with race detection  
make tests
# or
go test -race -timeout 210s ./...

# Run linting
make lint

# Run both linting and tests
make check

# Format code
make format
```

### Single Test Execution
```bash
# Run tests for a specific package
go test ./lib/executor/
go test ./internal/js/modules/k6/http/
go test -v -run TestSpecificFunction ./path/to/package/

# Run browser tests (requires special setup)
go test ./internal/js/modules/k6/browser/tests/
```

### Code Generation
```bash
# Install tools and regenerate generated code
make generate-tools-installs
make generate
```

### Working with Examples
```bash
# Run gRPC server example
make grpc-server-run

# Test scripts are in examples/ directory
./k6 run examples/http_get.js
./k6 run examples/browser/querying.js
```

## Architecture Overview

### Core Components

**Main Entry Point**: `main.go` → `cmd/execute.go` → `internal/cmd/root.go`
- The CLI is built with Cobra and organized into subcommands in `internal/cmd/`
- Key commands: `run`, `archive`, `cloud`, `inspect`, `new`, `pause`, `resume`, `scale`, `stats`, `status`, `version`

**JavaScript Runtime**: `internal/js/` and `js/`
- `internal/js/`: Core JavaScript execution engine using Sobek (Goja fork)
- `js/modules/`: Built-in k6 modules (http, html)
- `js/common/`: Shared JavaScript runtime utilities

**Load Testing Core**: `lib/`
- `lib/executor/`: Different execution strategies (constant VUs, ramping, arrival rate, etc.)
- `lib/netext/`: Network extensions and HTTP transport
- `lib/types/`: Core type definitions
- `lib/options.go`: Test configuration options

**Outputs**: `internal/output/` and `output/`
- Multiple output formats: JSON, CSV, InfluxDB, Prometheus, Cloud, OpenTelemetry
- Each output has its own package with config and implementation

**Browser Testing**: `internal/js/modules/k6/browser/`
- CDP-based browser automation using chromium
- Page, frame, element handle abstractions
- Browser context and session management

### Key Patterns

**Module System**: k6 modules are Go packages that expose JavaScript APIs
- `internal/js/modules/k6/`: Built-in k6 modules  
- Modules follow a mapping pattern to bridge Go and JavaScript
- Example: `k6/http` module maps HTTP functionality

**Executor Pattern**: Different load testing strategies implemented as executors
- `constant-vus`: Fixed number of virtual users
- `ramping-vus`: Gradually increasing/decreasing VUs  
- `constant-arrival-rate`: Fixed rate of iterations
- `per-vu-iterations`: Fixed iterations per VU

**Extension System**: `ext/` package allows extending k6 with custom functionality
- Extensions can add new JavaScript modules
- Used by xk6 ecosystem for community extensions

## Testing Structure

**Unit Tests**: Co-located with source code (`*_test.go`)
**Integration Tests**: `internal/cmd/tests/` for CLI integration tests  
**Browser E2E Tests**: `internal/js/modules/k6/browser/tests/` with static HTML fixtures
**TC39/WPT Conformance**: `internal/js/tc39/` and modules with WPT test suites

## Important Configuration Files

- `.golangci.yml`: Linter configuration (version pinned at top)
- `Makefile`: Build targets and development commands
- `go.mod`: Go module dependencies (see `go.mod` for the minimum required Go version)
- `Dependencies.md`: Dependency update policy and guidelines
- `modtools_frozen.yml`: Dependencies that should not be auto-updated

## Development Guidelines

**Code Style**: 
- Use `gofmt -s` for formatting
- Follow golangci-lint rules (run `make lint`)
- Comments should wrap at 100 characters

**Dependencies**:
- Update direct dependencies only after releases
- Some dependencies are intentionally frozen (see Dependencies.md)
- Use `modtools check --direct-only` to check for updates

**Testing**:
- All new code should have tests
- Use `go test -race` for concurrency testing
- Browser tests require additional setup and fixtures

**Generated Code**: 
- Several files are auto-generated (look for `*_gen.go`)
- Run `make generate` after modifying source templates
- Protobuf definitions in `internal/cloudapi/insights/proto/`

## Git Workflow and Branching Strategy

**Branching Strategy**:
- Create a new branch for each feature or bugfix
- Branch names must be descriptive and reflect the problem being solved
- Examples: `fix-http-timeout-handling`, `add-websocket-compression`, `improve-browser-element-selection`
- Base new branches off the `master` branch

**Allowed Git Commands**:
```bash
# Create and switch to new branch
git checkout -b descriptive-branch-name
git switch -c descriptive-branch-name

# Regular commits (using user from git config)
git add .
git commit -m "descriptive commit message"

# Push branch to remote
git push origin branch-name
git push -u origin branch-name  # first push with upstream