httpyac CLI Client

Common errors

• httpyac: command not found

  cause The `httpyac` CLI tool is not installed globally on your system, or its installation directory is not included in your system's PATH environment variable.
  fix Install `httpyac` globally using `npm install -g httpyac` (or `yarn global add httpyac`). Verify that your npm/yarn global bin directory is correctly added to your system's PATH.

• Error: Cannot find module 'httpyac'

  cause You are attempting to `import` or `require` the `httpyac` package programmatically, but it has not been installed as a local dependency in your project.
  fix Install `httpyac` as a local project dependency: `npm install httpyac` or `yarn add httpyac`.

• Error: Invalid HTTP file syntax at line X: ...

  cause The `.http` or `.rest` file you are trying to execute contains a syntax error, such as a malformed request line, incorrect header format, or an improperly defined variable or comment.
  fix Review the specified line number and the surrounding content in your `.http` file. Consult the `httpyac` documentation (or the IntelliJ HTTP Client specification which it largely follows) for correct syntax rules.

• SSL Handshake failed: self-signed certificate in certificate chain

  cause The target server uses an SSL certificate that is not trusted by your system's (or Node.js's) default Certificate Authorities, typically a self-signed certificate or one from an internal CA.
  fix For development or testing purposes, you can use the `--insecure` flag with the CLI (`httpyac send --insecure ...`) or set `insecure: true` in programmatic options. For production or secure environments, ensure the server has a valid, publicly trusted SSL certificate, or configure Node.js to explicitly trust your custom CA certificate.

• OAuth2: Invalid state error with authorization code flow

  cause During an OAuth2 authorization code flow, the `state` parameter returned by the authorization server does not match the original `state` parameter generated by `httpyac`, potentially due to an encoding issue or a mismatch in the flow.
  fix This specific issue (when the state parameter is percent-encoded) was fixed in `httpyac v6.16.7`. Ensure you are using `httpyac@6.16.7` or a newer version. If the problem persists, review your OAuth2 provider's configuration and ensure callback URLs are correctly configured and match.

Warnings

• breaking As of `v6.16.3`, the behavior of `@ref` (referenced HTTP regions) has changed significantly. Negative test results from a reference request no longer automatically stop the dependent request, and errored references are not executed multiple times if referenced repeatedly. This alters the flow of complex test suites.
  Fix: Review all test suites utilizing `@ref` directives. Modify dependent requests or test logic to explicitly check the results of referenced requests if their success is critical for subsequent steps, as the execution flow may no longer halt automatically.
• breaking Since `v6.16.2`, named response objects, which are often used to propagate variables, are only populated if *all* associated test results for that request are valid. Previously, named responses might have been available even with some test failures, which could lead to unexpected behavior in scripts relying on those variables.
  Fix: Ensure that all tests within a request region succeed if subsequent requests or scripts depend on variables derived from its named response. Update test assertions to pass consistently or refactor dependencies.
• gotcha While `httpyac` offers programmatic access and ships TypeScript types, its primary design and documentation focus is heavily on its command-line interface and VS Code extension. Developers seeking deep programmatic integration might encounter fewer high-level abstractions or dedicated library-specific guides compared to other packages.
  Fix: For complex programmatic use, consult the TypeScript declaration files (`.d.ts`) or the project's source code to understand available APIs. For simpler automation, consider executing the CLI directly using Node.js's `child_process` module.
• gotcha Using the `--insecure` CLI flag (or `insecure: true` in programmatic options) bypasses SSL certificate validation. This can expose connections to man-in-the-middle attacks and is generally not recommended for production environments or sensitive data.
  Fix: Only use `--insecure` for development or testing with self-signed certificates in controlled environments. For production, ensure target servers use valid, trusted SSL certificates, or properly configure your Node.js environment to trust custom Certificate Authorities.
• gotcha `httpyac` supports multiple mechanisms for defining variables and environments (e.g., `-e`, `--var`, `$env` placeholders, `.env` files, and `oauth2_proxy`). Understanding the precedence rules can be challenging, leading to unexpected variable values if not managed carefully.
  Fix: Refer to the `httpyac` documentation for the exact variable resolution order. For highest precedence in CLI calls, use the `--var` flag. For programmatic usage, ensure your `environments` object is structured clearly and accounts for potential overrides.

Install

• npm install httpyac npm
• yarn add httpyac yarn
• pnpm add httpyac pnpm

Imports

• executeFile
  wrong:

  const executeFile = require('httpyac')

  correct:

  import { executeFile } from 'httpyac'

  httpyac is an ESM-first package designed for Node.js environments. Prefer ES module imports. This is a primary function for programmatic execution of .http files.
• HttpYacConfig
  wrong:

  import { HttpYacConfig } from 'httpyac'

  correct:

  import type { HttpYacConfig } from 'httpyac'

  This is a TypeScript type definition for configuration options. Use 'import type' for clarity and to ensure it's removed from the compiled JavaScript bundle.
• processor
  wrong:

  import { Processor } from 'httpyac'

  correct:

  import { processor } from 'httpyac'

  The 'processor' object provides hooks and utilities for custom request handling, transformation, or extension; ensure correct casing as it is not a class constructor.

Quickstart

This quickstart demonstrates how to create a basic `.http` file with variables and multiple requests, and then execute it programmatically using the `httpyac` library in a TypeScript environment, logging the results.

// requests.http (e.g., in a file named 'example.http')

@user = testuser
@password = secretpassword

// A basic GET request to a public API endpoint
GET https://httpbin.org/basic-auth/{{user}}/{{password}}
Authorization: Basic {{user}} {{password}}
Accept: application/json

###

// A POST request with a JSON body and an environment variable
@apiBaseUrl = https://httpbin.org

POST {{apiBaseUrl}}/post
Content-Type: application/json

{
  "message": "Hello from httpyac!",
  "timestamp": "{{$isoTimestamp}}",
  "env_data": "{{$env.MY_APP_DATA ?? 'default'}}"
}

// JavaScript/TypeScript programmatic runner (e.g., 'run.ts')
import { executeFile } from 'httpyac';
import path from 'path';

async function runHttpYacFile() {
  // Path to your .http file
  const filePath = path.resolve(__dirname, './example.http');

  // Set an environment variable for the run (optional)
  process.env.MY_APP_DATA = 'important_value';

  try {
    const results = await executeFile(filePath, {
      // Options for execution
      log: console, // Use console for logging output
      all: true,    // Execute all requests in the file
      // Pass environment variables specific to this run
      environments: {
        development: { // An environment named 'development'
          token: 'my-auth-token'
        }
      },
      // Optionally specify a subset of requests by name or line number
      // name: 'POST request with a JSON body',
      // line: 10 // Line number of the request start
    });

    console.log('\n--- Execution Summary ---');
    results.forEach((exchange, index) => {
      console.log(`Request ${index + 1}: ${exchange.request.url}`);
      console.log(`  Status: ${exchange.response?.statusCode} ${exchange.response?.statusMessage}`);
      if (exchange.response?.body) {
        console.log(`  Body: ${exchange.response.body.toString().substring(0, 100)}...`);
      }
      if (exchange.testResults?.length) {
        console.log('  Tests:');
        exchange.testResults.forEach(test => console.log(`    - ${test.name}: ${test.result ? 'Passed' : 'Failed'}`));
      }
      if (exchange.error) {
        console.error(`  Error: ${exchange.error.message}`);
      }
    });
  } catch (error) {
    console.error('An unexpected error occurred during execution:', error);
  }
}

runHttpYacFile();