@assertrx/dino 1.0.9 → 1.0.11

package/skills/operating-k6-in-ci-cd/reference/ci-cd-pipelines.md

@@ -0,0 +1,265 @@
+# k6 CI/CD Pipeline Reference
+
+## GitHub Actions
+
+### Using Official Actions
+
+```yaml
+name: k6 Performance Test
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  k6-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup k6
+        uses: grafana/setup-k6-action@v1
+
+      - name: Run k6 test
+        uses: grafana/run-k6-action@v1
+        with:
+          path: tests/load-test.js
+        env:
+          BASE_URL: https://staging.example.com
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: k6-results
+          path: summary.json
+```
+
+### With Grafana Cloud k6
+
+```yaml
+jobs:
+  k6-cloud:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: grafana/setup-k6-action@v1
+      - name: Run k6 cloud test
+        uses: grafana/run-k6-action@v1
+        with:
+          path: tests/load-test.js
+          cloud-run-locally: true
+        env:
+          K6_CLOUD_TOKEN: ${{ secrets.K6_CLOUD_TOKEN }}
+```
+
+### Manual Setup (Without Official Actions)
+
+```yaml
+jobs:
+  k6-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install k6
+        run: |
+          sudo gpg -k
+          sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
+          echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
+          sudo apt-get update
+          sudo apt-get install k6
+
+      - name: Run load test
+        run: k6 run tests/load-test.js
+        env:
+          BASE_URL: ${{ vars.STAGING_URL }}
+          API_KEY: ${{ secrets.API_KEY }}
+```
+
+### Docker-Based
+
+```yaml
+jobs:
+  k6-docker:
+    runs-on: ubuntu-latest
+    container:
+      image: grafana/k6:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run test
+        run: k6 run tests/load-test.js
+```
+
+---
+
+## GitLab CI
+
+### Basic Configuration
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - test
+  - performance
+
+k6-load-test:
+  stage: performance
+  image:
+    name: grafana/k6:latest
+    entrypoint: ['']
+  script:
+    - k6 run tests/load-test.js
+  variables:
+    BASE_URL: https://staging.example.com
+  artifacts:
+    when: always
+    paths:
+      - summary.json
+    expire_in: 30 days
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+### With JSON Output
+
+```yaml
+k6-load-test:
+  stage: performance
+  image:
+    name: grafana/k6:latest
+    entrypoint: ['']
+  script:
+    - k6 run --out json=results.json tests/load-test.js
+  artifacts:
+    when: always
+    paths:
+      - results.json
+      - summary.json
+```
+
+### With Cloud Results
+
+```yaml
+k6-cloud-test:
+  stage: performance
+  image:
+    name: grafana/k6:latest
+    entrypoint: ['']
+  script:
+    - k6 cloud run --local-execution tests/load-test.js
+  variables:
+    K6_CLOUD_TOKEN: $K6_CLOUD_TOKEN
+```
+
+---
+
+## Jenkins
+
+### Pipeline (Declarative)
+
+```groovy
+pipeline {
+    agent any
+
+    environment {
+        BASE_URL = 'https://staging.example.com'
+    }
+
+    stages {
+        stage('Install k6') {
+            steps {
+                sh '''
+                    curl -sL https://github.com/grafana/k6/releases/latest/download/k6-linux-amd64.tar.gz | tar xz
+                    mv k6-*/k6 /usr/local/bin/
+                '''
+            }
+        }
+
+        stage('Run Load Test') {
+            steps {
+                sh 'k6 run tests/load-test.js'
+            }
+        }
+    }
+
+    post {
+        always {
+            archiveArtifacts artifacts: 'summary.json', allowEmptyArchive: true
+        }
+    }
+}
+```
+
+### Docker-Based Pipeline
+
+```groovy
+pipeline {
+    agent {
+        docker {
+            image 'grafana/k6:latest'
+            args '--entrypoint=""'
+        }
+    }
+
+    stages {
+        stage('Run Load Test') {
+            steps {
+                sh 'k6 run tests/load-test.js'
+            }
+        }
+    }
+}
+```
+
+---
+
+## Best Practices
+
+### Separate Test Stages
+
+```yaml
+# Run smoke test on every PR
+smoke-test:
+  script: k6 run --vus 3 --duration 30s tests/test.js
+
+# Run full load test on main branch only
+load-test:
+  script: k6 run tests/test.js
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+```
+
+### Environment Variables
+
+Always pass sensitive data via CI/CD secrets:
+```yaml
+env:
+  BASE_URL: ${{ vars.STAGING_URL }}     # Non-sensitive
+  API_KEY: ${{ secrets.API_KEY }}        # Sensitive
+  K6_CLOUD_TOKEN: ${{ secrets.K6_TOKEN }} # Cloud token
+```
+
+### Artifact Collection
+
+Always collect test results regardless of pass/fail:
+```yaml
+- name: Upload results
+  if: always()  # Runs even if test fails
+  uses: actions/upload-artifact@v4
+  with:
+    name: k6-results
+    path: |
+      summary.json
+      results.json
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Test completed, all thresholds passed |
+| 99 | Test completed, one or more thresholds failed |
+| Other | Test execution error |

package/skills/operating-k6-in-ci-cd/reference/extensions.md

@@ -0,0 +1,144 @@
+# k6 Extensions (xk6) Reference
+
+## Overview
+
+k6 extensions add capabilities beyond the core k6 feature set. Types:
+- **JavaScript extensions** — New JS APIs and modules
+- **Output extensions** — Send metrics to custom backends
+- **Secret source extensions** — Provide secrets at runtime
+
+## Automatic Resolution (k6 v1.2.0+)
+
+Official extensions auto-load when imported:
+
+```javascript
+import faker from 'k6/x/faker';    // Auto-resolved at runtime
+import sql from 'k6/x/sql';        // Auto-resolved at runtime
+```
+
+Community extensions require opt-in:
+
+```bash
+K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run script.js
+```
+
+## Building Custom k6 Binary (xk6)
+
+### Using Go
+
+```bash
+# Install xk6
+go install go.k6.io/xk6/cmd/xk6@latest
+
+# Build with extensions
+xk6 build \
+  --with github.com/grafana/xk6-faker \
+  --with github.com/grafana/xk6-sql
+
+# Build specific k6 version
+xk6 build v1.2.0 \
+  --with github.com/grafana/xk6-faker
+```
+
+### Using Docker
+
+```bash
+# Build custom binary
+docker run --rm -v $(pwd):/output grafana/xk6 build \
+  --with github.com/grafana/xk6-faker \
+  --output /output/k6
+
+# Run with custom binary
+./k6 run script.js
+```
+
+### Dockerfile for CI/CD
+
+```dockerfile
+FROM grafana/xk6 AS builder
+RUN xk6 build \
+  --with github.com/grafana/xk6-faker \
+  --with github.com/grafana/xk6-sql \
+  --output /k6
+
+FROM alpine:3
+COPY --from=builder /k6 /usr/local/bin/k6
+ENTRYPOINT ["k6"]
+```
+
+## Popular Official Extensions
+
+| Extension | Import | Description |
+|-----------|--------|-------------|
+| xk6-faker | `k6/x/faker` | Generate fake/random data |
+| xk6-sql | `k6/x/sql` | Database testing (PostgreSQL, MySQL, SQLite) |
+| xk6-disruptor | `k6/x/disruptor` | Fault injection for Kubernetes |
+
+## Popular Community Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| xk6-output-influxdb | Send metrics to InfluxDB |
+| xk6-kafka | Apache Kafka testing |
+| xk6-amqp | AMQP/RabbitMQ testing |
+| xk6-redis | Redis testing |
+| xk6-mqtt | MQTT protocol testing |
+| xk6-cable | ActionCable testing |
+| xk6-exec | Execute external commands |
+
+## Extension Usage Examples
+
+### xk6-faker (Data Generation)
+
+```javascript
+import faker from 'k6/x/faker';
+
+export default function () {
+  const user = {
+    name: faker.person.firstName() + ' ' + faker.person.lastName(),
+    email: faker.internet.email(),
+    phone: faker.phone.number(),
+    address: faker.location.streetAddress(),
+    company: faker.company.name(),
+  };
+
+  http.post(url, JSON.stringify(user), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+```
+
+### xk6-sql (Database Testing)
+
+```javascript
+import sql from 'k6/x/sql';
+import driver from 'k6/x/sql/driver/postgres';
+
+const db = sql.open(driver, 'postgres://user:pass@localhost:5432/testdb');
+
+export function setup() {
+  db.exec(`CREATE TABLE IF NOT EXISTS test (id SERIAL PRIMARY KEY, name VARCHAR(50))`);
+}
+
+export default function () {
+  db.exec(`INSERT INTO test (name) VALUES ('test_${Date.now()}')`);
+  const results = sql.query(db, 'SELECT COUNT(*) as count FROM test');
+}
+
+export function teardown() {
+  db.close();
+}
+```
+
+## Checking Dependencies
+
+```bash
+# Check what extensions a script needs
+k6 deps script.js
+```
+
+## Extension Discovery
+
+Browse available extensions:
+- Official: https://grafana.com/docs/k6/latest/extensions/
+- Community: https://github.com/topics/xk6

package/skills/operating-k6-in-ci-cd/reference/k6-operator.md

@@ -0,0 +1,214 @@
+# k6 Operator (Kubernetes Distributed Testing) Reference
+
+## Overview
+
+The k6-operator is a Kubernetes operator that enables running distributed k6 load tests across multiple pods. It uses a Custom Resource Definition (CRD) called `TestRun` (previously `K6`).
+
+## Installation
+
+### Using Helm
+
+```bash
+helm repo add grafana https://grafana.github.io/helm-charts
+helm repo update
+helm install k6-operator grafana/k6-operator \
+  --namespace k6-operator-system \
+  --create-namespace
+```
+
+### Using kubectl
+
+```bash
+# Install CRDs and operator
+kubectl apply -f https://github.com/grafana/k6-operator/releases/latest/download/bundle.yaml
+```
+
+### Verify Installation
+
+```bash
+kubectl get pods -n k6-operator-system
+# Should see k6-operator-controller-manager running
+```
+
+## TestRun CRD
+
+### Basic TestRun
+
+```yaml
+apiVersion: k6.io/v1alpha1
+kind: TestRun
+metadata:
+  name: k6-load-test
+spec:
+  parallelism: 4                  # Number of k6 pods
+  script:
+    configMap:
+      name: k6-test-script        # ConfigMap containing the test script
+      file: test.js               # Script filename in ConfigMap
+```
+
+### Creating the ConfigMap
+
+```bash
+# From file
+kubectl create configmap k6-test-script --from-file=test.js=./tests/load-test.js
+
+# Or inline
+kubectl apply -f - <<EOF
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: k6-test-script
+data:
+  test.js: |
+    import http from 'k6/http';
+    import { check } from 'k6';
+
+    export const options = {
+      vus: 50,
+      duration: '5m',
+    };
+
+    export default function () {
+      const res = http.get('http://my-service.default.svc.cluster.local:8080/api');
+      check(res, { 'status 200': (r) => r.status === 200 });
+    }
+EOF
+```
+
+### Running the Test
+
+```bash
+kubectl apply -f testrun.yaml
+
+# Monitor progress
+kubectl get testrun k6-load-test -w
+
+# Check pod logs
+kubectl logs -l k6_cr=k6-load-test -f
+```
+
+### Cleanup
+
+```bash
+kubectl delete testrun k6-load-test
+```
+
+## Advanced Configuration
+
+### With Arguments and Environment Variables
+
+```yaml
+apiVersion: k6.io/v1alpha1
+kind: TestRun
+metadata:
+  name: k6-load-test
+spec:
+  parallelism: 4
+  script:
+    configMap:
+      name: k6-test-script
+      file: test.js
+  arguments: --out json=/tmp/results.json
+  runner:
+    env:
+      - name: BASE_URL
+        value: "http://my-service.default.svc.cluster.local:8080"
+      - name: API_KEY
+        valueFrom:
+          secretKeyRef:
+            name: api-secrets
+            key: api-key
+    resources:
+      limits:
+        cpu: "500m"
+        memory: "512Mi"
+      requests:
+        cpu: "200m"
+        memory: "256Mi"
+```
+
+### With Extensions (Custom Image)
+
+```yaml
+spec:
+  runner:
+    image: custom-k6-image:latest   # Custom k6 image with extensions
+    imagePullPolicy: Always
+```
+
+### With Grafana Cloud k6
+
+```yaml
+spec:
+  parallelism: 4
+  script:
+    configMap:
+      name: k6-test-script
+      file: test.js
+  arguments: --out cloud
+  runner:
+    env:
+      - name: K6_CLOUD_TOKEN
+        valueFrom:
+          secretKeyRef:
+            name: k6-cloud-secrets
+            key: token
+```
+
+### With Istio Service Mesh
+
+When testing services behind Istio:
+
+```yaml
+spec:
+  runner:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: "true"    # Enable Istio sidecar
+```
+
+## Parallelism and Load Distribution
+
+Each pod runs the full test script independently. If your script defines `vus: 100` and `parallelism: 4`, each pod runs 100 VUs (400 total VUs).
+
+**To distribute load evenly:** Divide VUs by parallelism in your script or use environment variables:
+
+```javascript
+const PARALLELISM = parseInt(__ENV.K6_PARALLELISM) || 1;
+const TOTAL_VUS = 400;
+
+export const options = {
+  vus: Math.ceil(TOTAL_VUS / PARALLELISM),
+  duration: '5m',
+};
+```
+
+Or use scenarios with `constant-arrival-rate` for more predictable distribution.
+
+## TestRun Lifecycle
+
+```
+Created → Initialized → Started → Finished
+                                  ↓
+                              (cleanup)
+```
+
+**Monitor status:**
+```bash
+kubectl get testrun -w
+# NAME           STAGE       STATUS    AGE
+# k6-load-test   started    running   2m
+```
+
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Pods stuck in Pending | Check resource limits, node capacity |
+| ConfigMap not found | Verify ConfigMap exists in same namespace |
+| Connection refused | Check target service DNS and network policies |
+| Uneven load | Use arrival-rate executors for better distribution |
+| OOMKilled | Increase memory limits in runner.resources |