repository·main·Indexed 21 days ago
https://github.com/anweber/httpyacA command-line interface for executing .http and .rest files, supporting protocols including HTTP, REST, GraphQL, WebSocket, and gRPC. It features a `send` command for executing requests with support for environment variables, JSON and JUnit XML output formats, and a specialized `oauth2` command for generating authentication tokens.
You can install httpyac globally via npm or run it using Docker.
To install via npm:
npm install -g httpyacTo run via Docker (mounting your current directory to /data inside the container):
docker run -it -v ${PWD}:/data ghcr.io/anweber/httpyac:latest --versionnpm install -g httpyachttpYac is a CLI tool designed to quickly and easily send REST, SOAP, GraphQL, and gRPC requests. The CLI provides a default command for sending requests and a specialized command for OAuth2 authentication workflows.
# Example usage (conceptual based on command registration)
# The default command is used for sending requests
httpYac <request-options>
# The oauth2 command is used for OAuth2 flows
httpYac oauth2 <options>When executing the send command, you can filter the JSON output to only include requests that failed their associated tests. This is useful for CI/CD pipelines or automated testing workflows where you only care about the errors.
This is controlled via the filter option using the SendFilterOptions.onlyFailed setting. When applied, the requests array in the JSON output will only contain objects where summary.failedTests > 0.
When using the send command, you can target specific HTTP regions (individual requests or groups of requests) within your .http files using several selection criteria. This allows you to run a subset of your defined requests instead of the entire file.
You can filter regions using the following methods:
name defined in its metadata.tags. Tags are expected to be comma-separated strings in the metadata.httpyac will prompt you to choose a region from a list (e.g., filename: regionName or filename: all).--all flag to execute all regions in all discovered HTTP files.The testExitCode plugin is a CLI interceptor that automatically sets the process exit code based on the outcome of HTTP test results. This is useful for CI/CD pipelines to distinguish between different types of test failures.
When running tests via the CLI, the plugin monitors testResults and updates process.exitCode as follows:
| Condition | Exit Code |
|---|---|
An error occurred during a test (TestResultStatus.ERROR) | 19 |
A test failed its assertions (TestResultStatus.FAILED) | 20 |
An unexpected error occurred during the execution process (onError) | 10 |
Note: If multiple failure types exist, ERROR (19) takes precedence over FAILED (20).
You can define variables using the @name = value syntax and reference them in requests using {{name}}.
@user = doe
@password = 12345678
GET https://httpbin.org/basic-auth/{{user}}/{{password}}
Authorization: Basic {{user}} {{password}}Use the --output and --output-failed flags to specify how much information is printed for successful and failed requests. Available formats include:
short: Minimal information.body: Includes the response body.headers: Includes request and response headers.response: Includes response headers and response body length.exchange: Full details including request/response headers, body lengths, and timings.none: No output for the request.timings: Includes request timings.Use --raw to prevent the formatting of the response body.
# Example: Output full exchange details for successful requests
httpYac send test.http --output exchange
# Example: Output only headers for failed requests
httpYac send test.http --output-failed headersPass dynamic values to your HTTP files using the --var flag or select a specific environment using --env.
--var <variables...>: Accepts key-value pairs in the format key=value. If the value contains an =, it is treated as part of the value.--env <env...>: Specifies which environment(s) to use from your configuration.# Example: Pass a variable and select the 'production' environment
httpYac send test.http --var apiToken=secret123 --env productionThe EnvironmentConfig interface defines the global configuration for httpyac. It allows you to control cookie behavior, logging, proxy settings, request defaults, and environment variables.
Key configuration areas include:
cookieJarEnabled: Can be a boolean or an object to fine-tune cookie handling (e.g., allowSpecialUseDomain, looseMode, rejectPublicSuffixes, prefixSecurity).log: Configures output verbosity via level, ANSI color support, and CLI logger options.request: Sets default request behaviors like timeout, followRedirects, and rejectUnauthorized using the ConfigRequest interface.proxy & proxyExcludeList: Configures network proxying and a list of patterns to bypass the proxy.environments & envDirName: Manages environment-specific variables. You can specify a directory for environment files via envDirName.clientCertificates: A record of certificate options keyed by name.defaultHeaders: Global headers applied to all requests unless overwritten.plugins: A record of configuration objects for installed plugins.const config: EnvironmentConfig = {
cookieJarEnabled: {
looseMode: true
},
log: {
level: 'info',
supportAnsiColors: true
},
request: {
timeout: 5000,
followRedirects: true
},
proxy: 'http://localhost:8080',
proxyExcludeList: ['localhost', '127.0.0.1'],
defaultHeaders: {
'User-Agent': 'httpyac-client'
},
environments: {
dev: { /* variables */ },
prod: { /* variables */ }
}
};You can control how many times requests are executed and how they are scheduled using the following flags:
--repeat <count>: The number of times to repeat the requests.--repeat-mode <mode>: Determines if repeats happen sequential or parallel (default).--parallel <count>: Specifies the number of parallel requests to send (used when in parallel mode).# Example: Run requests 5 times in parallel with 3 concurrent workers
httpYac send test.http --repeat 5 --repeat-mode parallel --parallel 3Detailed options available when using the send command to execute HTTP files.
Usage: httpyac send [options] <fileName...>
Arguments:
fileName path to file or glob pattern
Options:
-a, --all execute all http requests in a http file
--bail stops when a test case fails
-e, --env <env...> list of environments
--filter <filter> filter requests output (only-failed)
--insecure allow insecure server connections when using ssl
-i --interactive do not exit the program after request, go back to selection
--json use json output
--junit use junit xml output
-l, --line <line> line of the http requests
-n, --name <name> name of the http requests
--no-color disable color support
-o, --output <output> output format of response (short, body, headers, response, exchange, none)
--output-failed <output> output format of failed response (short, body, headers, response, exchange, none)
--raw prevent formatting of response body
--quiet
--repeat <count> repeat count for requests
--repeat-mode <mode> repeat mode: sequential, parallel (default)
--parallel <count> send parallel requests
-s, --silent log only request
-t, --tag <tag...> list of tags to execute
--timeout <timeout> maximum time allowed for connections
--var <variables...> list of variables
-v, --verbose make the operation more talkative
-h, --help display help for commandThe httpyac CLI supports the following top-level commands and options.
Commands:
oauth2 [options]: Generate an OAuth2 token.send [options] <fileName...>: Send/execute HTTP files.help [command]: Display help for a command.Usage: httpyac [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
oauth2 [options] generate oauth2 token
send [options] <fileName...> send/ execute http files
help [command] display help for command