diff --git a/src/pages/bru-cli/_meta.js b/src/pages/bru-cli/_meta.js index 8b911a8..57e4d41 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 Actions", + "jenkins": "Jenkins CI" } diff --git a/src/pages/bru-cli/builtInReporters.mdx b/src/pages/bru-cli/builtInReporters.mdx index 296b21a..c3f564e 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 681696a..6bf69f8 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: - -```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 +To view a list of available options for Bruno CLI, run the following command: -# 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 + +| 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 | -## Adding Delay -If you need to add a delay between requests during the execution of your API collection, you can use the `--delay` option. +## Examples -Example: -```bash copy -bru run --delay 1000 -``` +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,48 +133,9 @@ 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 (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] | -| `--env [string]` | Specify environment to run with | -| `--env-var [string]` | Overwrite a single environment variable, multiple usages possible | -| `--sandbox [string]` | Javascript sandbox to use; available sandboxes are "developer" (default) or "safe" [string] [default: "developer"] | -| `-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 | - ## 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) diff --git a/src/pages/bru-cli/gitHubCLI.mdx b/src/pages/bru-cli/gitHubCLI.mdx new file mode 100644 index 0000000..de616c2 --- /dev/null +++ b/src/pages/bru-cli/gitHubCLI.mdx @@ -0,0 +1,98 @@ +import { Callout } from "nextra/components"; + +# 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. + + +## 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 +├── environments/ +│ ├── development.bru +│ ├── ci.bru +│ └── production.bru +└── bruno.json +``` + +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: '20' + + - 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 0000000..e8096a2 --- /dev/null +++ b/src/pages/bru-cli/jenkins.mdx @@ -0,0 +1,155 @@ +import { Callout } from "nextra/components"; + +# Jenkins CI Integration + +[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 + +* 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`. + +## Automate API Testing with Jenkins + + +### Step 1: Organize Your Bruno Collections + +Ensure your Bruno collections and environment files are properly organized within your Git repository. A typical structure looks like this: + +``` +your-api-project/ +├── Jenkinsfile +├── collections/ +│ ├── authentication/ +│ │ ├── login.bru +│ │ └── logout.bru +├── environments/ +│ ├── development.bru +│ ├── ci.bru +│ └── production.bru +└── bruno.json +``` + +### Step 2: Configure Node.js in Jenkins + +Before running Bruno CLI, you need to ensure Jenkins can access a Node.js runtime environment. + +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 // Run the pipeline on any available Jenkins agent + + stages { + stage('Checkout Code') { + steps { + // Clones the repository to the Jenkins workspace + checkout scm + } + } + + stage('Setup Node.js & Install Bruno CLI') { + steps { + // 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 Test Results') { + steps { + echo 'Archiving test report...' + // Save the generated HTML report as a build artifact + archiveArtifacts artifacts: 'results.html', fingerprint: true + } + } + } + + post { // Actions to run after the main pipeline stages complete + always { + echo 'Pipeline finished.' + } + success { + echo 'API Tests Passed Successfully!' + } + failure { + echo 'API Tests Failed! Check console output for details.' + } + } +} +``` + +### Step 4: Configure Jenkins Pipeline Job + +1. Create a New Jenkins Job: + + - 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. + +2. Configure Job Details: + + - 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). + +3. Click Save to finalize your job configuration. + +### 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: + + - 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 + +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 0000000..432d095 --- /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 --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 39bd77e..5fa07eb 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 --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 ce5e126..6900fa7 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, @@ -297,7 +297,7 @@ bru.sendRequest({ **Example:** ```javascript -bru.sendRequest({ +await bru.sendRequest({ method: 'POST', url: 'https://echo.usebruno.com', headers: {