From 7f32abea0812e9e2b4ff52a8da4e2e162a86eb7f Mon Sep 17 00:00:00 2001 From: ganesh-bruno Date: Mon, 23 Jun 2025 13:41:24 +0530 Subject: [PATCH 1/5] updated table --- src/pages/bru-cli/commandOptions.mdx | 37 +++++++++++----------------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/src/pages/bru-cli/commandOptions.mdx b/src/pages/bru-cli/commandOptions.mdx index 681696a3..9bbaf96a 100644 --- a/src/pages/bru-cli/commandOptions.mdx +++ b/src/pages/bru-cli/commandOptions.mdx @@ -165,42 +165,35 @@ Where: | ---------------------------- | ----------------------------------------------------------------------------- | | `-h`, `--help` | Show help | | `--version` | Show version number | -| `-r` | Indicates a recursive run (default: false) | -| `--cacert [string]` | CA certificate to verify peer against | -| `--ignore-truststore` | The specified custom CA certificate (--cacert) will be used exclusively and the default truststore is ignored [boolean] [default: false] | -| `--disable-cookies` | Automatically save and sent cookies with requests [boolean] [default: false] | +| `-r` | Indicates a recursive run [boolean] [default: false] | | `--env [string]` | Specify environment to run with | | `--env-var [string]` | Overwrite a single environment variable, multiple usages possible | +| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run | | `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] | +| `--tests-only` | Only run requests that have tests or active assertions | +| `--bail` | Stop execution after a failure of a request, test, or assertion | +| `--iteration-count [number]` | Number of times to run the collection | +| `--delay [number]` | Delay between each requests (in milliseconds) | +| `--csv-file-path` | CSV file to run the collection with | +| `--cacert [string]` | CA certificate to verify peer against | +| `--ignore-truststore` | Use custom CA certificate exclusively and ignore default truststore [boolean] [default: false] | +| `--client-cert-config` | Path to the Client certificate config file used for securing the connection | +| `--insecure` | Allow insecure server connections | +| `--disable-cookies` | Automatically save and send cookies with requests [boolean] [default: false] | +| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] | | `-o`, `--output [string]` | **[DEPRECATED]** Path to write file results to. Use reporter options instead | | `-f`, `--format [string]` | **[DEPRECATED]** Format of the file results. Use reporter options instead | | `--reporter-json [string]` | Path to generate a JSON report | | `--reporter-junit [string]` | Path to generate a JUnit report | | `--reporter-html [string]` | Path to generate an HTML report | -| `--insecure` | Allow insecure server connections | -| `--tests-only` | Only run requests that have tests or active assertions | -| `--bail` | Stop execution after a failure of a request, test, or assertion | -| `--csv-file-path` | CSV file to run the collection with | -| `--iteration-count [number]` | Number of times to run the collection | -| `--reporter--skip-all-headers` | Skip all headers in the report | -| `--reporter-skip-headers` | Skip specific headers in the report | -| `--client-cert-config` | Client certificate configuration by passing a JSON file | -| `--delay [number]` | Add delay to each request | -| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) | -| `--output-file [string]` | Output file to export as Bruno collection in JSON format | -| `--collection-name [string]` | Name for the imported collection from OpenAPI | | `--reporter-skip-all-headers` | Skip all headers in the report [boolean] [default: false] | | `--reporter-skip-headers` | Skip specific headers in the report [array] [default: []] | -| `--client-cert-config` | Path to the Client certificate config file used for securing the connection | -| `--delay [number]` | Delay between each requests (in milliseconds) | -| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] | | `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) | -| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run | - +| `--output-file [string]` | Output file to export as Bruno collection in JSON format | +| `--collection-name [string]` | Name for the imported collection from OpenAPI | ## Demo ![bru cli](/screenshots/cli-demo.webp) - ## Support If you encounter any issues or have any feedback or suggestions, please raise them on our [GitHub repository ↗](https://github.com/usebruno/bruno) From b5919769610c030359a7d6136f7e799045456d2a Mon Sep 17 00:00:00 2001 From: ganesh-bruno Date: Mon, 23 Jun 2025 13:46:20 +0530 Subject: [PATCH 2/5] added await keyword in js ref doc --- src/pages/testing/script/javascript-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/testing/script/javascript-reference.mdx b/src/pages/testing/script/javascript-reference.mdx index ce5e1261..de854de6 100644 --- a/src/pages/testing/script/javascript-reference.mdx +++ b/src/pages/testing/script/javascript-reference.mdx @@ -297,7 +297,7 @@ bru.sendRequest({ **Example:** ```javascript -bru.sendRequest({ +await bru.sendRequest({ method: 'POST', url: 'https://echo.usebruno.com', headers: { From 552ef780fdce0907a619ad9514d7c2343ae1997d Mon Sep 17 00:00:00 2001 From: ganesh-bruno Date: Tue, 24 Jun 2025 15:59:57 +0530 Subject: [PATCH 3/5] added docs for github ci actions --- src/pages/bru-cli/_meta.js | 5 +- src/pages/bru-cli/builtInReporters.mdx | 8 +- src/pages/bru-cli/commandOptions.mdx | 196 ++++++------------ src/pages/bru-cli/gitHubCLI.mdx | 95 +++++++++ src/pages/bru-cli/jenkins.mdx | 184 ++++++++++++++++ src/pages/bru-cli/proxyConfiguration.mdx | 45 ++++ src/pages/bru-cli/runCollection.mdx | 32 ++- .../testing/script/javascript-reference.mdx | 2 +- 8 files changed, 432 insertions(+), 135 deletions(-) create mode 100644 src/pages/bru-cli/gitHubCLI.mdx create mode 100644 src/pages/bru-cli/jenkins.mdx create mode 100644 src/pages/bru-cli/proxyConfiguration.mdx diff --git a/src/pages/bru-cli/_meta.js b/src/pages/bru-cli/_meta.js index 8b911a8f..7c4e625b 100644 --- a/src/pages/bru-cli/_meta.js +++ b/src/pages/bru-cli/_meta.js @@ -3,5 +3,8 @@ export default { "installation": "Installation", "commandOptions": "Command Options", "runCollection": "Run a Collection", - "builtInReporters": "Generate Reports" + "builtInReporters": "Generate Reports", + "proxyConfiguration": "Proxy Configuration", + "gitHubCLI": "GitHub CI", + "jenkins": "Jenkins CI" } diff --git a/src/pages/bru-cli/builtInReporters.mdx b/src/pages/bru-cli/builtInReporters.mdx index 296b21a7..c3f564ec 100644 --- a/src/pages/bru-cli/builtInReporters.mdx +++ b/src/pages/bru-cli/builtInReporters.mdx @@ -9,7 +9,7 @@ You can generate any combination of these reports and even run them simultaneous To generate a report in JSON format, use the `--reporter-json` option: ```bash copy -bru run request.bru --reporter-json results.json +bru run --reporter-json results.json ``` This will output the test results in a results.json file, which can be useful for further processing or programmatic analysis. @@ -19,7 +19,7 @@ This will output the test results in a results.json file, which can be useful fo To generate a report in JUnit format, use the `--reporter-junit` option: ```bash copy -bru run request.bru --reporter-junit results.xml +bru run --reporter-junit results.xml ``` The results.xml file will be in a format compatible with JUnit, making it ideal for integration with CI/CD pipelines that rely on JUnit reporting. @@ -30,7 +30,7 @@ The results.xml file will be in a format compatible with JUnit, making it ideal To generate a human-readable HTML report, use the `--reporter-html` option: ```bash copy -bru run request.bru --reporter-html results.html +bru run --reporter-html results.html ``` This will create an results.html file that provides a visual representation of the test outcomes, ideal for quick reviews. @@ -40,7 +40,7 @@ This will create an results.html file that provides a visual representation of t You can generate multiple reports at once by specifying more than one reporter option. For example, to generate JSON, JUnit, and HTML reports simultaneously, run: ```bash copy -bru run request.bru --reporter-json results.json --reporter-junit results.xml --reporter-html results.html +bru run --reporter-json results.json --reporter-junit results.xml --reporter-html results.html ``` This command will create three files: `results.json, results.xml, and results.html`, allowing you to analyze the results in different formats as needed. diff --git a/src/pages/bru-cli/commandOptions.mdx b/src/pages/bru-cli/commandOptions.mdx index 9bbaf96a..6bf69f8c 100644 --- a/src/pages/bru-cli/commandOptions.mdx +++ b/src/pages/bru-cli/commandOptions.mdx @@ -4,132 +4,106 @@ import { Callout } from "nextra/components"; Bruno CLI provides a variety of command options to help you customize your API testing and execution process. These options allow you to specify environments, configure reports, handle security, and much more. Below is a comprehensive list of available options: -## Bruno version -To check the current version of your Bruno CLI installation, use the following command: +## Options -```bash copy -bru --version -``` -This will display the version number of the Bruno CLI you have installed. It's a helpful command for ensuring you're working with the latest version or for troubleshooting version-specific issues. - -## Getting Started - -Navigate to the directory where your API collection resides, and run the following command: +To use options, add them to the bru run command after you specify the collection file or folder: -```bash copy -bru run +```bash +bru run [options] ``` -This will run all the requests in your collection. You can also run specific files or folders: +To view a list of available options for Bruno CLI, run the following command: -```bash copy -# Run a single file -bru run request.bru - -# Run multiple files -bru run request1.bru request2.bru - -# Run a folder -bru run folder - -# Run multiple folders -bru run folder1 folder2 - -# Mix of files and folders -bru run folder1 request1.bru folder2 request2.bru +```bash +bru run -h ``` -## Running Requests in a Folder -To run all the requests within a folder, use: +### Basic options -```bash copy -bru run folder -``` +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information | +| `--version` | Output the version number | -## Using Environments -If you need to use a specific environment, you can pass it with the `--env` option: +### Setup options -```bash copy -bru run folder --env Local -``` +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `--env [string]` | Specify environment to run with | +| `--env-var [string]` | Overwrite a single environment variable, multiple usages possible | +| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run | +| `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] | +| `--csv-file-path` | CSV file to run the collection with | +| `--json-file-path` | Path to the JSON data file | +| `--iteration-count [number]` | Number of times to run the collection | +| `-r` | Indicates a recursive run [boolean] [default: false] | -## Passing Environment Variables +### Request options - -Variables marked as secrets in Bruno app are not accessible via the CLI. Pass them directly as command-line arguments. - +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `--delay [number]` | Delay between each requests (in milliseconds) | +| `--tests-only` | Only run requests that have tests or active assertions | +| `--bail` | Stop execution after a failure of a request, test, or assertion | -```bash copy -bru run folder --env Local --env-var JWT_TOKEN=1234 -``` +### SSL & Security options -### Multiple Environment Variables +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `--cacert [string]` | CA certificate to verify peer against | +| `--ignore-truststore` | Use custom CA certificate exclusively and ignore default truststore [boolean] [default: false] | +| `--client-cert-config` | Path to the Client certificate config file used for securing the connection | +| `--insecure` | Allow insecure server connections | +| `--disable-cookies` | Automatically save and send cookies with requests [boolean] [default: false] | +| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] | -You can override multiple environment variables by using additional `--env-var` flags: +### Output & Reporting options -```bash copy -bru run folder --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234 -``` +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `-o`, `--output [string]` | **[DEPRECATED]** Path to write file results to. Use reporter options instead | +| `-f`, `--format [string]` | **[DEPRECATED]** Format of the file results. Use reporter options instead | +| `--reporter-json [string]` | Path to generate a JSON report | +| `--reporter-junit [string]` | Path to generate a JUnit report | +| `--reporter-html [string]` | Path to generate an HTML report | +| `--reporter-skip-all-headers` | Skip all headers in the report [boolean] [default: false] | +| `--reporter-skip-headers` | Skip specific headers in the report [array] [default: []] | -Each `--env-var` flag adds or overrides a single environment variable, and you can chain as many as needed. +### Import options -## Adding Delay -If you need to add a delay between requests during the execution of your API collection, you can use the `--delay` option. +| Option | Details | +| ---------------------------- | ----------------------------------------------------------------------------- | +| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) | +| `--output-file [string]` | Output file to export as Bruno collection in JSON format | +| `--collection-name [string]` | Name for the imported collection from OpenAPI | -Example: -```bash copy -bru run --delay 1000 -``` +## Examples + +This will run all the requests in your collection. -## Running Multiple Iterations -You can run a collection multiple times in a single command using the `--iteration-count` flag. This is useful for load testing or when you need to execute the same collection with different data sets. -Example: ```bash copy -bru run --iteration-count=2 +bru run ``` -This will execute the collection twice. You can specify any positive integer to control how many times the collection runs. - -## Using Client Certificates for API Requests - -If your API requests require client certificates for authentication, you can specify using the `--client-cert-config` option. The configuration should be provided in a JSON file. Here's an example of how to use this option: +You can also run specific files or folders: ```bash copy -bru run folder --client-cert-config /path/to/client-cert-config.json -``` +# Run a single file +bru run request.bru -The client-cert-config.json file should contain the following fields: - -```json -{ - "enabled": true, - "certs": [ - { - "domain": "usebruno.com", - "type": "cert", - "certFilePath": "certs/server_1.crt", - "keyFilePath": "private/server_1.key", - "passphrase": "Iu$eBrun0_#Secure!" - }, - { - "domain": "the-example.com", - "type": "pfx", - "pfxFilePath": "pfx/server_3.pfx", - "passphrase": "L!ghT_Y@g@mi_2024!" - } - ] -} -``` +# Run multiple files +bru run request1.bru request2.bru -## Disabling Proxies +# Run a folder +bru run folder -If you need to bypass all proxy settings (both collection-defined and system proxies) when running requests, you can use the `--noproxy` flag: +# Run multiple folders +bru run folder1 folder2 -```bash copy -bru run --noproxy +# Mix of files and folders +bru run folder1 request1.bru folder2 request2.bru ``` -The flag completely disables all proxy settings for that particular CLI run. ## Importing OpenAPI Specifications @@ -159,38 +133,6 @@ Where: - ``: Path to your OpenAPI specification file (can be either YAML or JSON format) - ``: Base path and filename for your JSON output -## Options - -| Option | Details | -| ---------------------------- | ----------------------------------------------------------------------------- | -| `-h`, `--help` | Show help | -| `--version` | Show version number | -| `-r` | Indicates a recursive run [boolean] [default: false] | -| `--env [string]` | Specify environment to run with | -| `--env-var [string]` | Overwrite a single environment variable, multiple usages possible | -| `--env-file [string]` | Path to the environment file (.bru) to use for the collection run | -| `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] | -| `--tests-only` | Only run requests that have tests or active assertions | -| `--bail` | Stop execution after a failure of a request, test, or assertion | -| `--iteration-count [number]` | Number of times to run the collection | -| `--delay [number]` | Delay between each requests (in milliseconds) | -| `--csv-file-path` | CSV file to run the collection with | -| `--cacert [string]` | CA certificate to verify peer against | -| `--ignore-truststore` | Use custom CA certificate exclusively and ignore default truststore [boolean] [default: false] | -| `--client-cert-config` | Path to the Client certificate config file used for securing the connection | -| `--insecure` | Allow insecure server connections | -| `--disable-cookies` | Automatically save and send cookies with requests [boolean] [default: false] | -| `--noproxy` | Disable all proxy settings (both collection-defined and system proxies) [boolean] [default: false] | -| `-o`, `--output [string]` | **[DEPRECATED]** Path to write file results to. Use reporter options instead | -| `-f`, `--format [string]` | **[DEPRECATED]** Format of the file results. Use reporter options instead | -| `--reporter-json [string]` | Path to generate a JSON report | -| `--reporter-junit [string]` | Path to generate a JUnit report | -| `--reporter-html [string]` | Path to generate an HTML report | -| `--reporter-skip-all-headers` | Skip all headers in the report [boolean] [default: false] | -| `--reporter-skip-headers` | Skip specific headers in the report [array] [default: []] | -| `--source [string]` | Path to the OpenAPI specification file (YAML or JSON) | -| `--output-file [string]` | Output file to export as Bruno collection in JSON format | -| `--collection-name [string]` | Name for the imported collection from OpenAPI | ## Demo ![bru cli](/screenshots/cli-demo.webp) diff --git a/src/pages/bru-cli/gitHubCLI.mdx b/src/pages/bru-cli/gitHubCLI.mdx new file mode 100644 index 00000000..4baa2b4c --- /dev/null +++ b/src/pages/bru-cli/gitHubCLI.mdx @@ -0,0 +1,95 @@ +import { Callout } from "nextra/components"; + +# GitHub Actions + +Bruno CLI integrates seamlessly with GitHub Actions to automate API testing workflows. Follow the below stpes to integrate GitHub Actions with Bruno CLI. + +## Automate API Testing with GitHub Actions + +1. Ensure your Bruno collections are properly organized in your repository: + +``` +your-api-project/ +├── .github/ +│ └── workflows/ +│ └── api-tests.yml +├── collections/ +│ ├── authentication/ +│ │ ├── login.bru +│ │ └── logout.bru +│ ├── users/ +│ │ ├── create-user.bru +│ │ ├── get-user.bru +│ │ └── update-user.bru +│ └── api/ +│ ├── health-check.bru +│ └── status.bru +├── environments/ +│ ├── development.bru +│ ├── staging.bru +│ └── production.bru +└── README.md +``` + +2. In your repository, create the following directory structure: + +```bash +mkdir -p .github/workflows +``` + +3. Create a new file `.github/workflows/api-tests.yml` sample script: + +```yaml +name: API Tests + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install Bruno CLI + run: npm install -g @usebruno/cli + + - name: Run API Tests + run: bru run --env ci --reporter-html results.html + + - name: Upload Test Results + uses: actions/upload-artifact@v4 + with: + name: test-results + path: results.html +``` + +4. **Commit and push** your workflow file: +```bash +git add .github/workflows/api-tests.yml +git commit -m "Add GitHub Actions workflow for API testing" +git push origin main +``` + +5. **Monitor the workflow**: + - Go to your GitHub repository + - Click on the "Actions" tab + - You should see your workflow running + +6. **View results**: + - Once completed, download the test results from the artifacts section + - Open `results.html` in your browser for detailed reports + +## Learn More + +For more advanced GitHub Actions features and configurations, visit the [GitHub Actions documentation](https://docs.github.com/en/actions). \ No newline at end of file diff --git a/src/pages/bru-cli/jenkins.mdx b/src/pages/bru-cli/jenkins.mdx new file mode 100644 index 00000000..5a5872a8 --- /dev/null +++ b/src/pages/bru-cli/jenkins.mdx @@ -0,0 +1,184 @@ +import { Callout } from "nextra/components"; + +# Jenkins CI + +Bruno CLI integrates seamlessly with Jenkins to automate your API testing workflows. This guide will walk you through setting up automated test execution using Jenkins CI. + +## Prerequisites + +Before setting up Jenkins CI with Bruno, ensure you have: + +1. **Jenkins server** installed and configured +2. **Git repository** containing your Bruno collections +3. **Bruno CLI** available on the Jenkins server + + + Make sure your Bruno collections are properly organized and tested locally before setting up CI/CD. + + +## Step 1: Organize Your Bruno Collections + +First, ensure your Bruno collections are properly organized in your repository: + +``` +your-api-project/ +├── Jenkinsfile +├── collections/ +│ ├── authentication/ +│ │ ├── login.bru +│ │ └── logout.bru +│ ├── users/ +│ │ ├── create-user.bru +│ │ ├── get-user.bru +│ │ └── update-user.bru +│ └── api/ +│ ├── health-check.bru +│ └── status.bru +├── environments/ +│ ├── development.bru +│ ├── staging.bru +│ └── production.bru +└── README.md +``` + +## Step 2: Create Jenkins Pipeline + +### Create Jenkinsfile + +Create a new file `Jenkinsfile` in your repository root with the following content: + +```groovy +pipeline { + agent any + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Setup Node.js') { + steps { + sh 'node --version' + sh 'npm --version' + } + } + + stage('Install Bruno CLI') { + steps { + sh 'npm install -g @usebruno/cli' + } + } + + stage('Run API Tests') { + steps { + sh 'bru run --env ci --reporter-html results.html' + } + } + + stage('Archive Results') { + steps { + archiveArtifacts artifacts: 'results.html', fingerprint: true + } + } + } + + post { + always { + echo 'API Tests completed!' + } + success { + echo 'All tests passed!' + } + failure { + echo 'Tests failed!' + } + } +} +``` + +## Step 3: Configure Jenkins Job + +1. **Create a new Pipeline job** in Jenkins: + - Go to Jenkins dashboard + - Click "New Item" + - Enter job name and select "Pipeline" + - Click "OK" + +2. **Configure the pipeline**: + - In "Pipeline" section, select "Pipeline script from SCM" + - Choose your SCM (Git) + - Enter your repository URL + - Set branch to `*/main` + - Set script path to `Jenkinsfile` + +3. **Save and run** the job + +## Sample Pipeline with Environment Variables + +If you need to use environment variables in your tests, here's an enhanced pipeline: + +```groovy +pipeline { + agent any + + environment { + API_BASE_URL = "${env.API_BASE_URL}" + API_KEY = "${env.API_KEY}" + } + + stages { + stage('Checkout') { + steps { + checkout scm + } + } + + stage('Setup Node.js') { + steps { + sh 'node --version' + sh 'npm --version' + } + } + + stage('Install Bruno CLI') { + steps { + sh 'npm install -g @usebruno/cli' + } + } + + stage('Run API Tests') { + steps { + sh 'bru run --env ci --env-var API_BASE_URL=$API_BASE_URL --env-var API_KEY=$API_KEY --reporter-html results.html' + } + } + + stage('Archive Results') { + steps { + archiveArtifacts artifacts: 'results.html', fingerprint: true + } + } + } + + post { + always { + echo 'API Tests completed!' + } + success { + echo 'All tests passed!' + } + failure { + echo 'Tests failed!' + } + } +} +``` + + + To use environment variables, configure them in Jenkins job settings under "Environment variables" or use Jenkins credentials for sensitive data. + + +## Learn More + +For more advanced Jenkins features and configurations, visit the [Jenkins documentation](https://www.jenkins.io/doc/). \ No newline at end of file diff --git a/src/pages/bru-cli/proxyConfiguration.mdx b/src/pages/bru-cli/proxyConfiguration.mdx new file mode 100644 index 00000000..e94a9cdf --- /dev/null +++ b/src/pages/bru-cli/proxyConfiguration.mdx @@ -0,0 +1,45 @@ +# Proxy Configuration + +Bruno CLI allows you to configure proxy settings directly from the terminal. You can also add client certificates through the CLI. + +Follow the steps below to set up configurations quickly and efficiently. + +## Disabling Proxies + +If you need to bypass all proxy settings (both collection-defined and system proxies) when running requests, you can use the `--noproxy` flag: + +```bash copy +bru run --noproxy +``` +The flag completely disables all proxy settings for that particular CLI run. + +## Using Client Certificates for API Requests + +If your API requests require client certificates for authentication, you can specify using the `--client-cert-config` option. The configuration should be provided in a JSON file. Here's an example of how to use this option: + +```bash copy +bru run folder --client-cert-config /path/to/client-cert-config.json +``` + +The client-cert-config.json file should contain the following fields: + +```json +{ + "enabled": true, + "certs": [ + { + "domain": "usebruno.com", + "type": "cert", + "certFilePath": "certs/server_1.crt", + "keyFilePath": "private/server_1.key", + "passphrase": "Iu$eBrun0_#Secure!" + }, + { + "domain": "the-example.com", + "type": "pfx", + "pfxFilePath": "pfx/server_3.pfx", + "passphrase": "L!ghT_Y@g@mi_2024!" + } + ] +} +``` \ No newline at end of file diff --git a/src/pages/bru-cli/runCollection.mdx b/src/pages/bru-cli/runCollection.mdx index 39bd77e6..f7c92711 100644 --- a/src/pages/bru-cli/runCollection.mdx +++ b/src/pages/bru-cli/runCollection.mdx @@ -59,7 +59,7 @@ bru run --iteration-count=2 This will execute the collection twice. This is useful for load testing or when you need to repeat the same set of requests multiple times. -## Running a Collection with Environment Files +## Running a Collection with Environments You can run a collection using environment variables from a `.bru` file. This allows you to attach environments via the CLI from anywhere in the filesystem. @@ -83,4 +83,32 @@ bru run --env-file /Users/username/projects/api-testing/environments/prod.bru The environment file should be in Bruno's `.bru` format. Make sure the file contains valid environment variables and their values. - \ No newline at end of file + + +### Using Environments Names + +If you need to use a specific environment, you can pass it with the `--env` option: + +```bash copy +bru run --env Local +``` + +#### Passing Environment Variables + + +Variables marked as secrets in Bruno app are not accessible via the CLI. Pass them directly as command-line arguments. + + +```bash copy +bru run --env Local --env-var JWT_TOKEN=1234 +``` + +## Multiple Environment Variables + +You can override multiple environment variables by using additional `--env-var` flags: + +```bash copy +bru run folder --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234 +``` + +Each `--env-var` flag adds or overrides a single environment variable, and you can chain as many as needed. \ No newline at end of file diff --git a/src/pages/testing/script/javascript-reference.mdx b/src/pages/testing/script/javascript-reference.mdx index de854de6..6900fa70 100644 --- a/src/pages/testing/script/javascript-reference.mdx +++ b/src/pages/testing/script/javascript-reference.mdx @@ -278,7 +278,7 @@ Send a programmatic HTTP request within your script. This allows you to make add **Syntax:** ```javascript -bru.sendRequest({ +await bru.sendRequest({ method: string, url: string, headers?: object, From 70ef0c3267eff06fb1068bbb4045a2d83f2b526f Mon Sep 17 00:00:00 2001 From: ganesh-bruno Date: Wed, 25 Jun 2025 18:34:43 +0530 Subject: [PATCH 4/5] added docs for cli --- src/pages/bru-cli/_meta.js | 2 +- src/pages/bru-cli/gitHubCLI.mdx | 25 +-- src/pages/bru-cli/jenkins.mdx | 205 ++++++++++------------- src/pages/bru-cli/proxyConfiguration.mdx | 2 +- src/pages/bru-cli/runCollection.mdx | 2 +- 5 files changed, 105 insertions(+), 131 deletions(-) diff --git a/src/pages/bru-cli/_meta.js b/src/pages/bru-cli/_meta.js index 7c4e625b..57e4d419 100644 --- a/src/pages/bru-cli/_meta.js +++ b/src/pages/bru-cli/_meta.js @@ -5,6 +5,6 @@ export default { "runCollection": "Run a Collection", "builtInReporters": "Generate Reports", "proxyConfiguration": "Proxy Configuration", - "gitHubCLI": "GitHub CI", + "gitHubCLI": "GitHub Actions", "jenkins": "Jenkins CI" } diff --git a/src/pages/bru-cli/gitHubCLI.mdx b/src/pages/bru-cli/gitHubCLI.mdx index 4baa2b4c..f204ca84 100644 --- a/src/pages/bru-cli/gitHubCLI.mdx +++ b/src/pages/bru-cli/gitHubCLI.mdx @@ -1,8 +1,18 @@ import { Callout } from "nextra/components"; -# GitHub Actions +# GitHub Actions Integration + +[GitHub Actions](https://docs.github.com/en/actions) is a powerful continuous integration and continuous delivery (CI/CD) platform that enables you to automate your software development workflows directly from your GitHub repository. It provides seamless integration with GitHub's ecosystem, making it an ideal choice for teams looking to automate their API testing workflows. + +Bruno CLI integrates seamlessly with GitHub Actions to automate API testing workflows. + + + + +## Prerequisites +- [Git](https://git-scm.com/downloads) Installed. +- GitHub repository with Bruno collection. -Bruno CLI integrates seamlessly with GitHub Actions to automate API testing workflows. Follow the below stpes to integrate GitHub Actions with Bruno CLI. ## Automate API Testing with GitHub Actions @@ -17,18 +27,11 @@ your-api-project/ │ ├── authentication/ │ │ ├── login.bru │ │ └── logout.bru -│ ├── users/ -│ │ ├── create-user.bru -│ │ ├── get-user.bru -│ │ └── update-user.bru -│ └── api/ -│ ├── health-check.bru -│ └── status.bru ├── environments/ │ ├── development.bru -│ ├── staging.bru +│ ├── ci.bru │ └── production.bru -└── README.md +└── bruno.json ``` 2. In your repository, create the following directory structure: diff --git a/src/pages/bru-cli/jenkins.mdx b/src/pages/bru-cli/jenkins.mdx index 5a5872a8..e8096a20 100644 --- a/src/pages/bru-cli/jenkins.mdx +++ b/src/pages/bru-cli/jenkins.mdx @@ -1,24 +1,21 @@ import { Callout } from "nextra/components"; -# Jenkins CI +# Jenkins CI Integration -Bruno CLI integrates seamlessly with Jenkins to automate your API testing workflows. This guide will walk you through setting up automated test execution using Jenkins CI. +[Jenkins](https://www.jenkins.io/) is a powerful open-source automation server that enables continuous integration and continuous delivery (CI/CD) for software development workflows. It provides a robust platform for automating build, test, and deployment processes across multiple environments and platforms. ## Prerequisites -Before setting up Jenkins CI with Bruno, ensure you have: +* A running Jenkins instance (local or remote). +* The [NodeJS Plugin](https://plugins.jenkins.io/nodejs/) installed in your Jenkins environment. +* A Git repository containing your Bruno collections and a `Jenkinsfile`. -1. **Jenkins server** installed and configured -2. **Git repository** containing your Bruno collections -3. **Bruno CLI** available on the Jenkins server +## Automate API Testing with Jenkins - - Make sure your Bruno collections are properly organized and tested locally before setting up CI/CD. - -## Step 1: Organize Your Bruno Collections +### Step 1: Organize Your Bruno Collections -First, ensure your Bruno collections are properly organized in your repository: +Ensure your Bruno collections and environment files are properly organized within your Git repository. A typical structure looks like this: ``` your-api-project/ @@ -27,157 +24,131 @@ your-api-project/ │ ├── authentication/ │ │ ├── login.bru │ │ └── logout.bru -│ ├── users/ -│ │ ├── create-user.bru -│ │ ├── get-user.bru -│ │ └── update-user.bru -│ └── api/ -│ ├── health-check.bru -│ └── status.bru ├── environments/ │ ├── development.bru -│ ├── staging.bru +│ ├── ci.bru │ └── production.bru -└── README.md +└── bruno.json ``` -## Step 2: Create Jenkins Pipeline +### Step 2: Configure Node.js in Jenkins -### Create Jenkinsfile +Before running Bruno CLI, you need to ensure Jenkins can access a Node.js runtime environment. -Create a new file `Jenkinsfile` in your repository root with the following content: +1. **Install the NodeJS Plugin:** + * Navigate to `Manage Jenkins` > `Plugins`. + * Select the `Available plugins` tab, search for "NodeJS", and install it. + +2. **Configure a Node.js Installation:** + * Go to `Manage Jenkins` > `Tools` (under `System Configuration`). + * Scroll down to the `NodeJS installations` section. + * Click `Add NodeJS`. + * Provide a descriptive **Name** (e.g., `Node.js 18`). This exact name will be used in your Jenkinsfile. + * Check `Install automatically` and select your desired `Node.js version` (e.g., `NodeJS 18.20.8`). + * **Crucially, ensure the checkbox "Provide Node & npm folder to PATH" is checked.** This ensures `node` and `npm` commands are available to your pipeline. + * Click `Save`. + +### Step 3: Create Your Jenkinsfile + +Create a file named `Jenkinsfile` in the root of your Git repository. This file defines the steps of your CI pipeline. ```groovy +// Sample Jenkinsfile pipeline { - agent any - + agent any // Run the pipeline on any available Jenkins agent + stages { - stage('Checkout') { + stage('Checkout Code') { steps { + // Clones the repository to the Jenkins workspace checkout scm } } - - stage('Setup Node.js') { - steps { - sh 'node --version' - sh 'npm --version' - } - } - - stage('Install Bruno CLI') { + + stage('Setup Node.js & Install Bruno CLI') { steps { - sh 'npm install -g @usebruno/cli' + // Makes the Node.js installation (configured in Jenkins Tools) available + tool 'Node.js 18' // Use the exact name configured in Jenkins Global Tool Configuration + + echo 'Verifying Node.js and npm versions...' + sh 'node -v' // Verify Node.js is on PATH + sh 'npm -v' // Verify npm is on PATH + + echo 'Installing Bruno CLI globally...' + sh 'npm install -g @usebruno/cli' // Install Bruno CLI + sh 'bru --version' // Verify Bruno CLI installation } } - + stage('Run API Tests') { steps { + // Ensure Node.js is available if this stage runs in a separate context + tool 'Node.js 18' + + echo 'Executing Bruno API tests...' + // Run tests with 'ci' environment and generate an HTML report sh 'bru run --env ci --reporter-html results.html' } } - - stage('Archive Results') { + + stage('Archive Test Results') { steps { + echo 'Archiving test report...' + // Save the generated HTML report as a build artifact archiveArtifacts artifacts: 'results.html', fingerprint: true } } } - - post { + + post { // Actions to run after the main pipeline stages complete always { - echo 'API Tests completed!' + echo 'Pipeline finished.' } success { - echo 'All tests passed!' + echo 'API Tests Passed Successfully!' } failure { - echo 'Tests failed!' + echo 'API Tests Failed! Check console output for details.' } } } ``` -## Step 3: Configure Jenkins Job +### Step 4: Configure Jenkins Pipeline Job -1. **Create a new Pipeline job** in Jenkins: - - Go to Jenkins dashboard - - Click "New Item" - - Enter job name and select "Pipeline" - - Click "OK" +1. Create a New Jenkins Job: -2. **Configure the pipeline**: - - In "Pipeline" section, select "Pipeline script from SCM" - - Choose your SCM (Git) - - Enter your repository URL - - Set branch to `*/main` - - Set script path to `Jenkinsfile` + - From the Jenkins Dashboard, click New Item. + - Enter an Item name (e.g., bruno-api-tests-pipeline). + - Select Pipeline as the item type and click OK. -3. **Save and run** the job +2. Configure Job Details: -## Sample Pipeline with Environment Variables + - In the job configuration page, navigate to the Pipeline section. + - Set Definition to Pipeline script from SCM and Choose your SCM (e.g., Git). + - Enter your Repository URL (e.g., `https://github.com/your-org/your-repo.git`). + - Specify any Credentials if your repository is private. + - Set Branches to build to ***/main** (or the branch containing your Jenkinsfile). + - Ensure Script Path is Jenkinsfile (this is the default). -If you need to use environment variables in your tests, here's an enhanced pipeline: +3. Click Save to finalize your job configuration. -```groovy -pipeline { - agent any - - environment { - API_BASE_URL = "${env.API_BASE_URL}" - API_KEY = "${env.API_KEY}" - } - - stages { - stage('Checkout') { - steps { - checkout scm - } - } - - stage('Setup Node.js') { - steps { - sh 'node --version' - sh 'npm --version' - } - } - - stage('Install Bruno CLI') { - steps { - sh 'npm install -g @usebruno/cli' - } - } - - stage('Run API Tests') { - steps { - sh 'bru run --env ci --env-var API_BASE_URL=$API_BASE_URL --env-var API_KEY=$API_KEY --reporter-html results.html' - } - } - - stage('Archive Results') { - steps { - archiveArtifacts artifacts: 'results.html', fingerprint: true - } - } - } - - post { - always { - echo 'API Tests completed!' - } - success { - echo 'All tests passed!' - } - failure { - echo 'Tests failed!' - } - } -} -``` +### Step 5: Run and Monitor Your Pipeline + +1. Trigger a Build: + + - From your Jenkins pipeline job page, click Build Now (in the left-hand menu) to manually start the pipeline. + +2. Monitor Progress: + + - Observe the Build History section to see the status of your builds (green checkmark for success, red cross mark for failure). + - Click on a specific build number, then select Console Output to view real-time logs and detailed execution steps. + +3. View Test Results: - - To use environment variables, configure them in Jenkins job settings under "Environment variables" or use Jenkins credentials for sensitive data. - + - Once a build that generated results.html completes, navigate to that specific build's page. + - Look for the **Artifacts** section (usually on the left sidebar or at the top of the build summary). + - Click on `results.html` to download the report, then open it in your web browser for detailed test outcomes. ## Learn More diff --git a/src/pages/bru-cli/proxyConfiguration.mdx b/src/pages/bru-cli/proxyConfiguration.mdx index e94a9cdf..432d095c 100644 --- a/src/pages/bru-cli/proxyConfiguration.mdx +++ b/src/pages/bru-cli/proxyConfiguration.mdx @@ -18,7 +18,7 @@ The flag completely disables all proxy settings for that particular CLI run. If your API requests require client certificates for authentication, you can specify using the `--client-cert-config` option. The configuration should be provided in a JSON file. Here's an example of how to use this option: ```bash copy -bru run folder --client-cert-config /path/to/client-cert-config.json +bru run --client-cert-config /path/to/client-cert-config.json ``` The client-cert-config.json file should contain the following fields: diff --git a/src/pages/bru-cli/runCollection.mdx b/src/pages/bru-cli/runCollection.mdx index f7c92711..5fa07ebd 100644 --- a/src/pages/bru-cli/runCollection.mdx +++ b/src/pages/bru-cli/runCollection.mdx @@ -108,7 +108,7 @@ bru run --env Local --env-var JWT_TOKEN=1234 You can override multiple environment variables by using additional `--env-var` flags: ```bash copy -bru run folder --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234 +bru run --env Local --env-var JWT_TOKEN=1234 --env-var API_KEY=abcd1234 ``` Each `--env-var` flag adds or overrides a single environment variable, and you can chain as many as needed. \ No newline at end of file From 1d03e926cef2b264f0419241a3c01662428f7c31 Mon Sep 17 00:00:00 2001 From: ganesh-bruno Date: Thu, 26 Jun 2025 11:11:07 +0530 Subject: [PATCH 5/5] updated node version --- src/pages/bru-cli/gitHubCLI.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/bru-cli/gitHubCLI.mdx b/src/pages/bru-cli/gitHubCLI.mdx index f204ca84..de616c21 100644 --- a/src/pages/bru-cli/gitHubCLI.mdx +++ b/src/pages/bru-cli/gitHubCLI.mdx @@ -62,7 +62,7 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '18' + node-version: '20' - name: Install Bruno CLI run: npm install -g @usebruno/cli