The source code is available on GitHub at https://github.com/christianhelle/argiope.

Like my previous Zig project, GitHub Copilot wrote most of the boilerplate, including the GitHub workflows, README, install scripts, and snapcraft.yaml file. The entire project took a few evenings to build.

How it works

The crawler uses a Breadth-first search (BFS) approach to traverse web pages. It starts with a seed URL, fetches the page, extracts all links, and adds them to a queue for processing. Each URL is normalized and checked against a visited set to avoid processing the same URL twice.

pub const Crawler = struct {
    allocator: std.mem.Allocator,
    base_url: []u8,
    base_host: []u8,
    queue: std.ArrayListUnmanaged(QueueEntry) = .empty,
    visited: std.StringHashMapUnmanaged(void) = .empty,
    results: std.ArrayListUnmanaged(CrawlResult) = .empty,
    options: CrawlOptions,

    pub fn init(allocator: std.mem.Allocator, url: []const u8, options: CrawlOptions) Crawler {
        const base_url = allocator.dupe(u8, url) catch "";
        const base_host = url_mod.extractHost(base_url) orelse "";
        return .{
            .allocator = allocator,
            .base_url = base_url,
            .base_host = base_host,
            .options = options,
        };
    }

    pub fn crawl(self: *Crawler) !void {
        try self.queue.append(self.allocator, .{
            .url = try self.allocator.dupe(u8, self.base_url),
            .depth = 0,
        });

        if (self.options.parallel) {
            try self.crawlParallel();
        } else {
            try self.crawlSequential();
        }
    }
};

The tool supports both sequential and parallel crawling. In parallel mode, a thread pool processes multiple URLs concurrently, which significantly speeds up crawling for sites with many links.

Domain restriction is enforced by extracting the host from each URL and comparing it to the base URL’s host. External links are still checked for broken status but not followed for further crawling. This keeps the crawler focused on the target site while still validating outbound links.

pub fn isInternal(self: *const Crawler, url: []const u8) bool {
    const host = url_mod.extractHost(url) orelse return false;
    return std.mem.eql(u8, host, self.base_host);
}

HTML Parsing

Rather than pulling in a full HTML parser dependency, I wrote a lightweight scanner that extracts links and image sources. It iterates through the HTML looking for opening tags and extracts href attributes from anchor tags and src attributes from image tags.

pub fn extractLinks(allocator: std.mem.Allocator, html: []const u8) ![]Link {
    var links: std.ArrayListUnmanaged(Link) = .empty;

    var pos: usize = 0;
    while (pos < html.len) {
        const tag_start = std.mem.indexOfPos(u8, html, pos, "<") orelse break;
        pos = tag_start + 1;
        if (pos >= html.len) break;

        // Skip comments
        if (pos + 2 < html.len and html[pos] == '!' and
            html[pos + 1] == '-' and html[pos + 2] == '-') {
            const comment_end = std.mem.indexOfPos(u8, html, pos, "-->") orelse break;
            pos = comment_end + 3;
            continue;
        }

        // Read tag name and extract attributes...
        const tag_name = html[tag_name_start..pos];

        // Determine what attribute we're looking for
        const attr_name: ?[]const u8 = blk: {
            if (asciiEqlIgnoreCase(tag_name, "a") or
                asciiEqlIgnoreCase(tag_name, "link") or
                asciiEqlIgnoreCase(tag_name, "area"))
            {
                break :blk "href";
            }
            if (asciiEqlIgnoreCase(tag_name, "img") or
                asciiEqlIgnoreCase(tag_name, "script") or
                asciiEqlIgnoreCase(tag_name, "source"))
            {
                break :blk "src";
            }
            break :blk null;
        };

        // Extract and store the attribute value...
    }

    return links.toOwnedSlice(allocator);
}

The scanner also handles srcset attributes on image tags, parsing the comma-separated list of image URLs. It skips JavaScript, mailto, tel, data URLs, and fragment-only links.

URL Normalization

URL handling is surprisingly complex. Relative URLs need to be resolved against the base URL, query parameters may need to be normalized, and trailing slashes should be handled consistently.

pub fn resolve(allocator: std.mem.Allocator, base: []const u8, href: []const u8) ![]u8 {
    // Absolute URL
    if (std.mem.indexOf(u8, href, "://") != null) {
        return allocator.dupe(u8, href);
    }

    // Protocol-relative URL
    if (std.mem.startsWith(u8, href, "//")) {
        const proto = extractProtocol(base) orelse "https";
        return std.fmt.allocPrint(allocator, "{s}:{s}", .{ proto, href });
    }

    // Absolute path
    if (href.len > 0 and href[0] == '/') {
        const origin = try extractOrigin(allocator, base);
        defer allocator.free(origin);
        return std.fmt.allocPrint(allocator, "{s}{s}", .{ origin, href });
    }

    // Relative path
    const base_dir = extractDirectory(base);
    return std.fmt.allocPrint(allocator, "{s}/{s}", .{ base_dir, href });
}

The normalize function ensures URLs are in a consistent form by converting to lowercase (for the scheme and host), removing default ports, and collapsing path segments.

HTTP Client

The tool uses Zig’s standard library HTTP client with custom timeout and redirect handling. Each request is wrapped with a timeout to avoid hanging on unresponsive servers.

pub const FetchOptions = struct {
    max_redirects: u8 = 5,
    timeout_ms: u32 = 10_000,
    max_body_size: usize = 10 * 1024 * 1024,
};

pub fn fetch(
    client: *std.http.Client,
    allocator: std.mem.Allocator,
    url: []const u8,
    options: FetchOptions,
) !FetchResult {
    const uri = try std.Uri.parse(url);

    var req = try client.open(.GET, uri, .{
        .server_header_buffer = try allocator.alloc(u8, 16384),
    });
    defer req.deinit();

    req.send() catch |err| {
        return FetchResult{
            .status = 0,
            .body = null,
            .error_msg = try allocator.dupe(u8, @errorName(err)),
        };
    };

    try req.wait();

    const status = @intFromEnum(req.response.status);

    // Handle redirects
    if (status >= 300 and status < 400 and options.max_redirects > 0) {
        const location = req.response.headers.getFirstValue("location") orelse {
            return error.InvalidRedirect;
        };
        // Follow redirect...
    }

    // Read response body...
    const body = try req.reader().readAllAlloc(allocator, options.max_body_size);

    return FetchResult{
        .status = @intCast(status),
        .body = body,
        .error_msg = null,
    };
}

The client handles HTTP redirects up to a configurable limit and collects both the status code and response body. Errors during the request are captured and returned as part of the result rather than propagated, allowing the crawler to continue processing other URLs.

Command Line Interface

The CLI supports two main commands: check for broken link detection and images for downloading images. Options include crawl depth, timeout, request delay, and output format.

pub const Command = enum {
    check,
    images,
    help,
    version_cmd,
};

pub const Options = struct {
    command: Command = .help,
    url: ?[]const u8 = null,
    depth: u16 = 3,
    timeout_ms: u32 = 10_000,
    delay_ms: u32 = 100,
    output_dir: []const u8 = "./download",
    verbose: bool = false,
    parallel: bool = false,
    report: ?[]const u8 = null,
    report_format: ReportFormat = .text,
    include_positives: bool = false,
};

pub fn parseArgs(args: []const []const u8) !Options {
    var opts = Options{};

    if (args.len < 2) return opts;

    var i: usize = 1;
    while (i < args.len) : (i += 1) {
        const arg = args[i];

        if (std.mem.eql(u8, arg, "check")) {
            opts.command = .check;
        } else if (std.mem.eql(u8, arg, "images")) {
            opts.command = .images;
        } else if (std.mem.startsWith(u8, arg, "--depth")) {
            // Parse depth value...
        } else if (std.mem.startsWith(u8, arg, "--timeout")) {
            // Parse timeout value...
        } else if (!std.mem.startsWith(u8, arg, "-")) {
            opts.url = arg;
        }
    }

    return opts;
}

The parser iterates through command-line arguments, identifying commands, flags, and values. It handles both short (-v) and long (--verbose) flag formats.

Report Generation

The tool generates reports in three formats: plain text, Markdown, and HTML. Reports can include just broken links or all checked URLs depending on the --include-positives flag.

pub fn write(
    allocator: std.mem.Allocator,
    path: []const u8,
    format: cli_mod.ReportFormat,
    url: []const u8,
    results: []const crawler_mod.CrawlResult,
    summary: summary_mod.CheckSummary,
    include_positives: bool,
) !void {
    const file = try std.fs.cwd().createFile(path, .{ .truncate = true });
    defer file.close();

    var buf: [65536]u8 = undefined;
    var fw = file.writer(&buf);
    const w = &fw.interface;

    switch (format) {
        .text => try writeText(w, url, results, summary, include_positives),
        .markdown => try writeMarkdown(w, url, results, summary, include_positives),
        .html => try writeHtml(allocator, w, url, results, summary, include_positives),
    }

    try w.flush();
}

The HTML report is self-contained with inline CSS and uses a card-based layout with color-coded status badges. This makes it suitable for embedding in CI/CD pipelines or sharing as a standalone file.

Usage

The basic usage is straightforward. Run argiope check <url> to scan a website for broken links:

$ argiope check https://christianhelle.com --depth 3

Crawling https://christianhelle.com (depth=3, timeout=10s)...

------------------------------------------------------------------------
Status   Type       Time(ms)   URL
------------------------------------------------------------------------
404      internal   45         https://christianhelle.com/missing-page
------------------------------------------------------------------------

Summary:
  Total URLs checked: 127
  OK:                 126
  Broken:             1
  Errors:             0
  Internal:           115
  External:           12

Timing:
  Total crawl time:   2345ms
  Avg response time:  18ms
  Min response time:  8ms
  Max response time:  156ms

For downloading images, use the images command:

$ argiope images https://example.com/gallery -o ./images

Downloading images from https://example.com/gallery...

Downloaded: page_1/image_1.jpg
Downloaded: page_1/image_2.jpg
Downloaded: page_2/image_1.png
...

Downloaded 42 images to ./images

Generate a report file instead of printing to the console:

argiope check https://christianhelle.com --report report.html --report-format html

argiope check https://christianhelle.com --report report.md --report-format markdown --include-positives

Use parallel crawling for faster processing on sites with many links:

argiope check https://christianhelle.com --parallel --depth 5

Distribution

Like my previous Zig project, I wanted simple distribution across platforms. GitHub Copilot generated the installation scripts and snapcraft configuration.

The install.sh script downloads the latest release for Linux or macOS:

#!/usr/bin/env bash
set -e

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case $ARCH in
    x86_64) ARCH="x86_64" ;;
    aarch64|arm64) ARCH="aarch64" ;;
    *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
esac

case $OS in
    linux) PLATFORM="linux-$ARCH" ;;
    darwin) PLATFORM="macos-$ARCH" ;;
    *) echo "Unsupported OS: $OS"; exit 1 ;;
esac

URL="https://github.com/christianhelle/argiope/releases/latest/download/argiope-$PLATFORM"

curl -L "$URL" -o argiope
chmod +x argiope
sudo mv argiope /usr/local/bin/

echo "argiope installed successfully!"

For Windows users, install.ps1 does the same:

$ErrorActionPreference = "Stop"

$url = "https://github.com/christianhelle/argiope/releases/latest/download/argiope-windows-x86_64.exe"
$dest = "$env:USERPROFILE\bin\argiope.exe"

New-Item -ItemType Directory -Force -Path (Split-Path $dest) | Out-Null
Invoke-WebRequest -Uri $url -OutFile $dest

Write-Host "argiope installed to $dest"
Write-Host "Add $env:USERPROFILE\bin to your PATH if needed."

The snapcraft.yaml configuration allows publishing to the Snap Store:

name: argiope
base: core22
version: "0.1.0"
summary: A web crawler for broken-link detection
description: |
  A fast, multi-threaded web crawler that detects broken links,
  generates reports, and downloads images.
grade: stable
confinement: strict

apps:
  argiope:
    command: bin/argiope
    plugs:
      - network
      - home

The GitHub Actions workflow builds binaries for all platforms and attaches them to releases:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-linux
          - os: ubuntu-latest
            target: aarch64-linux
          - os: macos-latest
            target: x86_64-macos
          - os: macos-latest
            target: aarch64-macos
          - os: windows-latest
            target: x86_64-windows

Conclusion

Building Argiope was a great exercise in working with Zig’s standard library, particularly the HTTP client and file system APIs. The tool is fast, produces a single static binary with zero dependencies, and runs on Linux, macOS, and Windows.

If you need to check your website for broken links or download images from web pages, give Argiope a try. The source code is on GitHub at https://github.com/christianhelle/argiope.

The source code for the new extension is available on GitHub.

The Evolution of an Extension

The original version of this extension (source code available on GitHub) was built using the traditional Visual Studio SDK. It served its purpose well, but as with any software built on older frameworks, it began to show its age.

The “Dependency Hell” of In-Process Extensions

One of the most significant pain points with the old Visual Studio SDK is that extensions run in-process with Visual Studio. This means your extension shares the same memory space and dependencies as the IDE itself.

A classic example of this is Newtonsoft.Json. If your extension depends on version 13.0.1, but Visual Studio has loaded version 12.0.3 for its own internal use, you enter “Dependency Hell”. You’re forced to use binding redirects, assembly loading hacks, or simply hope for the best.

By moving to the new out-of-process extensibility model, the extension runs in its own isolated process. This architecture provides several key benefits:

1. True Isolation: The extension runs on .NET 8.0, completely independent of the .NET Framework 4.8 runtime that powers Visual Studio.
2. No More Binding Redirects: I can use any version of any library I want—including System.Text.Json or newer versions of Newtonsoft.Json—without clashing with Visual Studio’s dependencies.
3. Improved Stability: If the extension crashes, it doesn’t take down the entire IDE with it.

From “Custom Tools” to Explicit Commands

In the previous version, the extension relied on the Single File Generator (or “Custom Tool”) mechanism. This is a legacy feature where you select a file in Solution Explorer, go to the Properties window, and type a magic string like RefitterCodeGenerator into the “Custom Tool” field.

While this felt “integrated,” it had significant drawbacks:

• Discoverability: Users had to know the magic string to type.
• Silent Failures: If the generation failed, it was often difficult to see why without digging into the Output window.
• Blocking the UI: The generation happened on the UI thread, freezing Visual Studio for large API specifications.

The new extension abandons this pattern in favor of explicit context menu commands. You now simply right-click an OpenAPI file and select “Generate Client Code”.

Architecture Comparison: Entry Points

The difference in how the extension is initialized is striking. The old model used the AsyncPackage class, decorated with a multitude of attributes to register menus, tool windows, and options pages.

Old VSPackage Entry Point - VsPackage.cs:

[Guid("47AFE4E1-5A52-4FE1-8CA7-EDB8310BDA4A")]
[ProvideMenuResource("Menus.ctmenu", 1)]
[ProvideUIContextRule(...)]
[ProvideOptionPage(typeof(GeneralOptionPage), VsixName, GeneralOptionPage.Name, 0, 0, true)]
public sealed class VsPackage : AsyncPackage
{
    private readonly ICommandInitializer[] commands = {
        new AutoRestCodeGeneratorCustomToolSetter(),
        new NSwagCodeGeneratorCustomToolSetter(),
        // ...
    };

    protected override async Task InitializeAsync(
        CancellationToken cancellationToken,
        IProgress<ServiceProgressData> progress)
    {
        await JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);
        await base.InitializeAsync(cancellationToken, progress);

        foreach (var command in commands)
            await command.InitializeAsync(this, cancellationToken);
    }
}

The new model uses a cleaner, more modern approach. The entry point inherits from Extension, and we use Dependency Injection right out of the box.

New Extension Entry Point - ExtensionEntrypoint.cs:

[VisualStudioContribution]
internal class ExtensionEntrypoint : Extension
{
    public override ExtensionConfiguration ExtensionConfiguration => new()
    {
        Metadata = new(
            id: "f7530eb1-1ce9-46ac-8fab-165b68cf3d61",
            version: ExtensionAssemblyVersion,
            displayName: "REST API Client Code Generator (PREVIEW)",
            description: "Generate REST API client code from OpenAPI/Swagger specifications")
    };

    [VisualStudioContribution]
    public static MenuConfiguration GenerateMenu => new("%ApiClientCodeGenerator.GroupDisplayName%")
    {
        Placements = [KnownPlacements.ItemNode],
        Children = [
            MenuChild.Command<Commands.GenerateRefitterCommand>(),
            MenuChild.Command<Commands.GenerateNSwagCommand>(),
            // ...
        ],
    };

    protected override void InitializeServices(IServiceCollection serviceCollection)
    {
        serviceCollection.AddSingleton<ExtensionSettingsProvider>();
        base.InitializeServices(serviceCollection);
    }
}

Notice how we can register services like ExtensionSettingsProvider using standard .NET dependency injection patterns (InitializeServices).

Modernizing Commands and Async Execution

One of the biggest improvements in the new model is that everything is async by default. In the old SDK, you had to carefully manage thread switching to avoid “UI delays” or deadlocks. The original version of the extension uses single file generators as a custom tool. A custom tool is a COM component that implements the IVsSingleFileGenerator interface. Implementing single-file generators in 2026 feels really outdated.

Old Command Implementation - SingleFileCodeGenerator.cs:

[ComVisible(true)]
public abstract class SingleFileCodeGenerator : IVsSingleFileGenerator
{
    public int Generate(
        string wszInputFilePath,
        string bstrInputFileContents,
        string wszDefaultNamespace,
        IntPtr[] rgbOutputFileContents,
        out uint pcbOutput,
        IVsGeneratorProgress pGenerateProgress)
    {
        // Strict thread affinity check required
        if (!TestingUtility.IsRunningFromUnitTest)
            ThreadHelper.ThrowIfNotOnUIThread();

        // Blocking generation on the UI thread
        var codeGenerator = Factory.Create(...);
        var code = codeGenerator.GenerateCode();

        // Report progress
    }
}

In the new model, we simply implement ExecuteCommandAsync and use the IClientContext to interact with the IDE.

New Command Implementation (RefitterCommands.cs):

[VisualStudioContribution]
public class GenerateRefitterCommand(TraceSource traceSource, ExtensionSettingsProvider settingsProvider)
    : GenerateRefitterBaseCommand(traceSource, settingsProvider)
{
    public override async Task ExecuteCommandAsync(
        IClientContext context,
        CancellationToken cancellationToken)
    {
        // Fully async execution without UI thread blocking
        await GenerateCodeAsync(
            await context.GetInputFileAsync(cancellationToken),
            await context.GetDefaultNamespaceAsync(cancellationToken),
            cancellationToken);
    }
}

Background Progress Reporting

Since our code generation can take a few seconds (or more for large specs), providing feedback is essential. The new SDK makes it incredibly easy to show a progress indicator in the Visual Studio status bar or a background task window.

Here’s how easy it is to implement:

public async Task GenerateCodeAsync(...)
{
    using var progress = await Extensibility.Shell().StartProgressReportingAsync(
        "Generating code with Refitter",
        new ProgressReporterOptions(true), // true = indeterminate/cancellable
        cancellationToken);

    progress.Report(10, $"Starting Refitter code generation for: {inputFilename}");

    // Do the heavy lifting...
    var csharpCode = await GenerateCodeInternalAsync(..., progress, cancellationToken);

    progress.Report(90, "Writing generated code...");
    await File.WriteAllTextAsync(outputFile, csharpCode, cancellationToken);
}

A New Settings Experience

The old Visual Studio SDK used the DialogPage class to create options pages, which often looked like standard Windows Forms property grids. The new model introduces a modern, declarative way to define settings.

Here’s an example of how settings are defined in the new model. We simply define a static class with properties decorated with the [VisualStudioContribution] attribute:

internal static class GeneralSettings
{
    [VisualStudioContribution]
    internal static SettingCategory GeneralCategory { get; } = new("general", "%Settings.General.DisplayName%", SettingsRoot.RootCategory)
    {
        Description = "%Settings.General.Description%",
        GenerateObserverClass = true,
        Order = 0,
    };

    [VisualStudioContribution]
    internal static Setting.String JavaPath { get; } = new(
        "javaPath",
        "%Settings.JavaPath.DisplayName%",
        GeneralCategory,
        string.Empty)
    {
        Description = "%Settings.JavaPath.Description%",
    };

    // ... other settings
}

Reading these settings is also straightforward and fully asynchronous:

public class ExtensionSettingsProvider(VisualStudioExtensibility extensibility)
{
    public async Task<IGeneralOptions> GetGeneralOptionsAsync(CancellationToken cancellationToken)
    {
        var values = await extensibility.Settings().ReadEffectiveValuesAsync(
        [
            GeneralSettings.JavaPath,
            GeneralSettings.NpmPath,
            GeneralSettings.NSwagPath,
            // ...
        ],
        cancellationToken);

        return new GeneralOptions(values);
    }
}

I’ve migrated all the tool-specific settings to this new API. Here is what the new settings UI looks like:

We can now define settings for each generator, such as NSwag, AutoRest, and Refitter, with rich UI support.

Dialogs and User Input

Sometimes we need input from the user, like a URL for an OpenAPI specification. In the old days, I would have had to build a custom WPF Window or Windows Form. Now, I can use the built-in ShowPromptAsync method for a consistent, native look and feel.

This snippet from CommandExtensions.cs shows how we prompt for a URL:

public static async Task<string?> AddNewOpenApiFileAsync(
    this Command command,
    IClientContext context,
    CancellationToken cancellationToken)
{
    var inputUrl = await command.Extensibility.Shell().ShowPromptAsync(
        "Enter URL to OpenAPI Specifications",
        new InputPromptOptions
        {
            DefaultText = "Example: https://petstore3.swagger.io/api/v3/openapi.json",
            Icon = ImageMoniker.KnownValues.URLInputBox,
            Title = "REST API Client Code Generator",
        },
        cancellationToken);

    return inputUrl;
}

Creating Custom Dialogs with XAML

For more complex scenarios, like the About Dialog, the new model allows us to define UI using standard XAML data templates. This is a huge win for maintainability, as we can separate the UI definition from the logic.

Here’s a snippet of the XAML definition for the About Dialog:

<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:vs="http://schemas.microsoft.com/visualstudio/extensibility/2022/xaml">
  <StackPanel Orientation="Vertical" MinWidth="500" Margin="20">
    <TextBlock FontSize="18" FontWeight="Bold" Margin="0,0,0,10"
               Text="{Binding DisplayName}" />

    <TextBlock FontSize="12" Margin="0,0,0,5"
               Text="{Binding Description}" TextWrapping="Wrap" />

    <StackPanel Orientation="Horizontal" Margin="0,10,0,5">
      <TextBlock FontWeight="SemiBold" Text="Version: " />
      <TextBlock Text="{Binding Version}" />
    </StackPanel>

    <!-- ... more UI elements ... -->
  </StackPanel>
</DataTemplate>

And the backing C# model uses the RemoteUserControl base class:

internal class AboutDialog(
    VisualStudioExtensibility extensibility,
    string displayName,
    string description,
    string version)
    : RemoteUserControl(new AboutDialogData(extensibility, displayName, description, version))
{
    [DataContract]
    internal class AboutDialogData : NotifyPropertyChangedObject
    {
        [DataMember]
        public string DisplayName { get; set; }

        [DataMember]
        public string Description { get; set; }

        [DataMember]
        public string Version { get; set; }

        // ...
    }
}

This clean separation of concerns makes building custom UI in Visual Studio extensions much more pleasant.

Code Reuse: The Core Library

Despite the massive architectural shift in the VSIX project, the “brains” of the operation—the code generation logic—remain largely unchanged.

Both the old (Dev17) and new (Extensibility) projects reference the same Core Library. This ensures that regardless of which version of the extension you use, the generated code quality and features remain identical. This made the migration much smoother, as I only had to focus on the “plumbing” of the extension rather than rewriting the generators themselves.

Conclusion

Migrating to the new Visual Studio Extensibility model has been a significant step forward. The performance gains from .NET 8.0, the stability of the out-of-process model, and the improved developer experience with modern APIs make it well worth the effort.

If you’re a Visual Studio extension author, I highly recommend looking into this new model. And if you’re a user of the REST API Client Code Generator, I hope you enjoy the faster, more stable experience!

The source code is available on GitHub at https://github.com/christianhelle/clocz.

It only took me an evening to build, and GitHub Copilot wrote the GitHub workflows, README, install scripts, and the snapcraft.yaml file.

How it works

The implementation is quite straightforward. It uses std.fs.Dir.iterate to walk the directory tree. For each file found, a job is spawned in a std.Thread.Pool. This allows the tool to process multiple files in parallel, maximizing I/O and CPU usage.

fn walkDir(
    allocator: std.mem.Allocator,
    dir: std.fs.Dir,
    dir_path: []const u8,
    results: *results_mod.Results,
    pool: *std.Thread.Pool,
) !void {
    var iter = dir.iterate();
    while (try iter.next()) |entry| {
        // ... (skip hidden files and node_modules)

        const entry_path = try std.fs.path.join(allocator, &.{ dir_path, entry.name });
        switch (entry.kind) {
            .directory => {
                // ... (recursive call)
            },
            .file => {
                // Ownership of entry_path transfers to the job; the job frees it.
                pool.spawn(processFile, .{JobContext{
                    .allocator = allocator,
                    .path = entry_path,
                    .results = results,
                }}) catch {
                    allocator.free(entry_path);
                };
            },
            else => allocator.free(entry_path),
        }
    }
}

I added some basic filtering to skip hidden files (starting with .) and directories like node_modules and vendor, as these usually contain dependencies rather than source code. There’s also a file size limit of 128MB to avoid loading massive files into memory.

For language detection, I went with a simple extension-based lookup. The file extension is extracted, lower cased, and matched against a list of known languages. It supports over 60 languages, handling single-line and block comments specific to each language.

const entries = [_]Entry{
    // C family
    .{ .ext = "c",        .lang = cStyle("C") },
    .{ .ext = "h",        .lang = cStyle("C") },
    .{ .ext = "cpp",      .lang = cStyle("C++") },
    .{ .ext = "cc",       .lang = cStyle("C++") },
    .{ .ext = "cxx",      .lang = cStyle("C++") },
    .{ .ext = "hpp",      .lang = cStyle("C++") },
    .{ .ext = "hxx",      .lang = cStyle("C++") },
    .{ .ext = "cs",       .lang = cStyle("C#") },
    .{ .ext = "java",     .lang = cStyle("Java") },
    // and more...

pub fn detect(path: []const u8) ?Language {
    const ext = std.fs.path.extension(path);
    if (ext.len <= 1) return null;
    const ext_no_dot = ext[1..];

    // Lowercase into a small stack buffer (extensions are short)
    var buf: [32]u8 = undefined;
    if (ext_no_dot.len > buf.len) return null;
    const ext_lower = std.ascii.lowerString(buf[0..ext_no_dot.len], ext_no_dot);

    for (entries) |entry| {
        if (std.mem.eql(u8, entry.ext, ext_lower)) return entry.lang;
    }
    return null;
}

The actual line counting logic is a single-pass scan over the file content. It counts blank lines, single-line comments, block comments, and code lines. It uses a state machine-like approach to track if it’s inside a block comment, which handles nested comments and comments starting mid-line.

pub const Counts = struct {
    files: u64 = 0,
    blank: u64 = 0,
    comment: u64 = 0,
    code: u64 = 0,
};

pub fn countLines(buf: []const u8, lang: languages.Language) Counts {
    var counts = Counts{ .files = 1 };
    var in_block = false;

    // Strip a trailing newline so we don't count an extra blank line for it.
    const data = if (buf.len > 0 and buf[buf.len - 1] == '\n') buf[0 .. buf.len - 1] else buf;

    var lines = std.mem.splitScalar(u8, data, '\n');
    while (lines.next()) |raw_line| {
        // Trim \r for Windows line endings and leading/trailing whitespace.
        const line = std.mem.trim(u8, raw_line, " \t\r");

        if (line.len == 0) {
            counts.blank += 1;
            continue;
        }

        // Inside a block comment.
        if (in_block) {
            counts.comment += 1;
            if (lang.block_comment_end) |bce| {
                if (std.mem.indexOf(u8, line, bce) != null) {
                    in_block = false;
                }
            }
            continue;
        }

        // ... (check for start of block comment or single line comment)

        // It's a code line.
        counts.code += 1;

        // Check whether a block comment opens mid-line (e.g. `x = 1; /* start`).
        if (lang.block_comment_start) |bcs| {
            if (std.mem.indexOf(u8, line, bcs)) |bcs_pos| {
                // ... (check if block comment ends on same line)
            }
        }
    }

    return counts;
}

Command Line Parsing

Currently the tool only really a single functional argument, which is the folder to scan. I manually iterate through the arguments provided by std.process.argsAlloc. The implementation checks for flags like -h or --help and interprets any non-flag argument as the target directory path. If an unknown option is encountered, it helpfully prints the usage information and exits.

pub fn init(allocator: std.mem.Allocator) !Cli {
    const args = try std.process.argsAlloc(allocator);
    defer std.process.argsFree(allocator, args);

    // ...

    var path: []const u8 = ".";
    for (args[1..]) |arg| {
        if (std.mem.startsWith(u8, arg, "-h") or std.mem.startsWith(u8, arg, "--help")) {
            options.help = true;
        } else if (std.mem.startsWith(u8, arg, "-v") or std.mem.startsWith(u8, arg, "--version")) {
            options.version = true;
        } else if (arg.len > 0 and arg[0] != '-') {
            path = arg;
        } else {
            // ... (print error and exit)
        }
    }

    // ...
}

Performance and Progress

One of the goals was to see how fast Zig can be compared to the original Perl version. The tool reads files into memory buffers using readToEndAlloc (up to 128MB) and quickly scans for line breaks and comments. It also detects binary files to avoid counting them as source code.

/// Returns true if the buffer looks like a binary file (null byte in first 8KB).
pub fn isBinary(buf: []const u8) bool {
    const check = @min(buf.len, 8192);
    return std.mem.indexOfScalar(u8, buf[0..check], 0) != null;
}

While the main thread and worker threads are busy scanning, a separate thread runs a simple progress loop. It sleeps for 100ms and prints the current count of scanned files (\rScanning... {d} files), giving visual feedback without slowing down the processing.

pub fn loop(self: *ProgressPrinter) void {
    const stderr = std.fs.File.stderr();
    while (self.running.load(.acquire)) {
        std.Thread.sleep(100 * std.time.ns_per_ms);
        if (!self.running.load(.acquire)) break;
        const n = self.results.files_scanned.load(.monotonic);
        var buf: [64]u8 = undefined;
        const msg = std.fmt.bufPrint(&buf, "\rScanning... {d} files", .{n}) catch break;
        stderr.writeAll(msg) catch {};
    }
}

The final output is a sorted table showing the number of files, blank lines, comments, and code lines for each language, along with the total time taken and files processed per second.

Usage

The CLI is simple. You run clocz to scan the current directory, or clocz [path] to scan a specific directory. The -h and -v flags show help and version info respectively.

Here’s an example of the output for scanning a reasonably large system with a backend written in C# and a React frontend, running on a 10-year-old laptop with an Intel Core i7-7660U @ 4x 4GHz CPU with 8GB of RAM:

Scanned 10822 files

------------------------------------------------------------------------
Language                          files    blank    comment       code
------------------------------------------------------------------------
C#                                 4045    26273      19500     170743
TSX                                 720     5119       1248      58860
TypeScript                          726     4123       2585      43640
Markdown                             59     1347          0       4480
CSS                                   9      370         52       2889
PowerShell                           40      460        305       2046
HTML                                  4       32         12       1619
JavaScript                            4      193        167       1034
Shell                                 4       22         14        108
XML                                   1        0          0          9
------------------------------------------------------------------------
SUM:                               5612    37939      23883     285428
------------------------------------------------------------------------
Time=0.50s  (11203.0 files/s)

The tool is a single static binary with zero external dependencies, making it easy to distribute and run on Linux, macOS, and Windows.

Distribution

Since I’m lazy and wanted this to be easy to use, I asked GitHub Copilot to help me set up the distribution channels. It generated the install.sh and install.ps1 scripts for quick installation on Linux/macOS and Windows respectively using the latest Release version on Github.

It also wrote the snapcraft.yaml file so I could publish clocz to the Snap Store.

name: clocz
base: core22
version: '0.1.0'
summary: A fast line counter written in Zig
description: |
  A fast, multi-threaded command-line tool for counting lines of code.
grade: stable
confinement: strict

The GitHub Actions workflow (release.yml) builds binaries for Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64) and attaches them to the GitHub Release.

Conclusion

I was pleasantly surprised by how productive I could be with Zig after working with it on-and-off for half a year, building a performant and cross-platform tool in such a short amount of time. If you want to check it out or contribute, the source code is on GitHub at https://github.com/christianhelle/clocz.

In this post, I’ll explore how to use HTTP File Runner (or httprunner), a command-line tool I built in Rust, to execute advanced integration test scenarios using .http files. We’ll cover everything from variable management to conditional execution and CI/CD integration.

Getting Started

First, ensure you have httprunner installed. You can install it via a simple script or download a release from the GitHub repository.

# Linux/macOS
curl -fsSL https://christianhelle.com/httprunner/install | bash

# Windows
irm https://christianhelle.com/httprunner/install.ps1 | iex

If you’re on Ubuntu then you can also install it using snap

snap install httprunner

Once installed, you can run any .http file:

httprunner tests.http

Global Variables

You can define global variables at the top of your .http file using the @ syntax. This is perfect for values that are reused across multiple requests, like a base URL.

@HostAddress = https://httpbin.org
@ContentType = application/json

GET {{HostAddress}}/get
Content-Type: {{ContentType}}

Built-in Functions

httprunner provides built-in functions for dynamic value generation in your .http files. Functions are case-insensitive and automatically generate values when the request is executed.

Available Functions

guid() - Generate UUID

Generates a new UUID v4 (Universally Unique Identifier) in simple format (32 hex characters without dashes).

POST https://api.example.com/users
Content-Type: application/json

{
  "id": "guid()",
  "requestId": "GUID()"
}

string() - Generate Random String

Generates a random alphanumeric string of 20 characters.

POST https://api.example.com/test
Content-Type: application/json

{
  "sessionKey": "string()",
  "token": "STRING()"
}

number() - Generate Random Number

Generates a random number between 0 and 100 (inclusive).

POST https://api.example.com/data
Content-Type: application/json

{
  "randomValue": "number()",
  "percentage": "NUMBER()"
}

base64_encode() - Base64 Encoding

Encodes a string to Base64 format. The string must be enclosed in single quotes.

POST https://api.example.com/auth
Content-Type: application/json

{
  "credentials": "base64_encode('username:password')",
  "token": "BASE64_ENCODE('Hello, World!')"
}

upper() - Convert to Uppercase

Converts a string to uppercase. The string must be enclosed in single quotes.

POST https://api.example.com/data
Content-Type: application/json

{
  "code": "upper('hello, world')",
  "shout": "UPPER('quiet text')"
}

lower() - Convert to Lowercase

Converts a string to lowercase. The string must be enclosed in single quotes.

POST https://api.example.com/data
Content-Type: application/json

{
  "normalized": "lower('HELLO, WORLD')",
  "lowercase": "LOWER('Mixed Case Text')"
}

name() - Generate Full Name

Generates a random full name (first name + last name).

POST https://api.example.com/users
Content-Type: application/json

{
  "fullName": "name()",
  "displayName": "NAME()"
}

first_name() - Generate First Name

Generates a random first name.

POST https://api.example.com/users
Content-Type: application/json

{
  "firstName": "first_name()",
  "givenName": "FIRST_NAME()"
}

last_name() - Generate Last Name

Generates a random last name.

POST https://api.example.com/users
Content-Type: application/json

{
  "lastName": "last_name()",
  "surname": "LAST_NAME()"
}

address() - Generate Address

Generates a random full mailing address (street, city, postal code, country).

POST https://api.example.com/users
Content-Type: application/json

{
  "streetAddress": "address()",
  "mailingAddress": "ADDRESS()"
}

email() - Generate Email Address

Generates a random email address in the format firstname.lastname@domain.com.

POST https://api.example.com/users
Content-Type: application/json

{
  "email": "email()",
  "contactEmail": "EMAIL()"
}

job_title() - Generate Job Title

Generates a random job title.

POST https://api.example.com/users
Content-Type: application/json

{
  "title": "job_title()",
  "position": "JOB_TITLE()"
}

lorem_ipsum(n) - Generate Lorem Ipsum Text

Generates Lorem Ipsum placeholder text with the specified number of words. The parameter n determines how many words to generate.

POST https://api.example.com/content
Content-Type: application/json

{
  "summary": "lorem_ipsum(20)",
  "description": "LOREM_IPSUM(50)",
  "content": "Lorem_Ipsum(100)"
}

getdate() - Get Current Date

Returns the current local date in YYYY-MM-DD format.

POST https://api.example.com/events
Content-Type: application/json

{
  "eventDate": "getdate()",
  "createdDate": "GETDATE()"
}

gettime() - Get Current Time

Returns the current local time in HH:MM:SS format (24-hour).

POST https://api.example.com/logs
Content-Type: application/json

{
  "timestamp": "gettime()",
  "logTime": "GETTIME()"
}

getdatetime() - Get Current Date and Time

Returns the current local date and time in YYYY-MM-DD HH:MM:SS format.

POST https://api.example.com/records
Content-Type: application/json

{
  "createdAt": "getdatetime()",
  "timestamp": "GETDATETIME()"
}

getutcdatetime() - Get Current UTC Date and Time

Returns the current UTC date and time in YYYY-MM-DD HH:MM:SS format.

POST https://api.example.com/records
Content-Type: application/json

{
  "utcTimestamp": "getutcdatetime()",
  "serverTime": "GETUTCDATETIME()"
}

Environment Variables

For different environments (development, staging, production), you shouldn’t hard code values. httprunner supports loading variables from a http-client.env.json file, compatible with the VS Code REST Client extension. In most cases, the environment file would contain secrets like API keys or tokens that you don’t want to commit to version control.

Create a http-client.env.json file:

{
  "dev": {
    "HostAddress": "https://dev-api.example.com",
    "ApiKey": "dev-secret"
  },
  "prod": {
    "HostAddress": "https://api.example.com",
    "ApiKey": "prod-secret"
  }
}

Reference these variables in your .http file:

GET {{HostAddress}}/users
Authorization: Bearer {{ApiKey}}

Then run httprunner with the --env flag:

httprunner tests.http --env dev

Generating Environment Files

Manually managing http-client.env.json files can be tedious, especially when dealing with short-lived tokens or multiple environments. I recommend scripting the generation of this file.

Here is an example PowerShell script that fetches access tokens from Azure CLI and generates a comprehensive environment file for localhost, Docker, and development environments:

$management_api_tokens = az account get-access-token `
  --scope app://api.example.net/dev/management_api/.default | ConvertFrom-Json

$simulator_tokens = az account get-access-token `
  --scope app://api.example.net/dev/simulator/.default | ConvertFrom-Json

$environment = @{
  localhost = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "http://localhost:8900"
    simulator = "http://localhost:8901"
    management_api = "http://localhost:8150"
  }
  docker = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "http://host.docker.internal:8900"
    simulator = "http://host.docker.internal:8901"
    management_api = "http://host.docker.internal:8150"
  }
  dev = @{
    authorization = "Bearer " + $management_api_tokens.accessToken
    simulator_authorization = "Bearer " + $simulator_tokens.accessToken
    cpo = "https://ocpi.example.net"
    simulator = "https://ocpi-simulator.example.net"
    management_api = "https://management-api.example.net"
  }
}

Set-Content -Path ./http-client.env.json -Value ($environment | ConvertTo-Json -Depth 10)

Delays

Rate limiting is a common constraint when testing APIs. httprunner allows you to introduce delays either globally or per request. My personal use case would be eventually consistent systems where you want to wait for a certain state before proceeding.

To add a delay between every request in a run, use the CLI flag:

httprunner tests.http --delay 500

For more granular control, use comments in your .http file:

# @pre-delay 1000
# @post-delay 500
GET https://httpbin.org/get

• @pre-delay: Wait before sending the request (in milliseconds).
• @post-delay: Wait after the request completes (in milliseconds).

Timeouts

Network conditions can be unpredictable. You can configure timeouts to fail tests if an API is too slow. If you’re testing against a local development server, you might want to set a shorter timeout than the default 30 seconds.

# Wait up to 5 seconds for a response
# @timeout 5000 ms
GET https://api.example.net/delay/2

# Custom connection timeout (default is 30s)
# @connection-timeout 10 s
GET https://api.example.net/get

Supported units include ms, s, and m.

Request Chaining

One of the most powerful features for integration testing is chaining requests—using data from a previous response in a subsequent request. httprunner supports extracting values from headers, JSON bodies, and even the original request data.

Request Variable Syntax

The syntax for request variables is:

{{<request_name>.<source>.<part>.<path>}}

• request_name: The name defined via # @name <name>
• source: request or response
• part: body or headers
• path: The specific value to extract

Extraction Patterns

• JSON Bodies: Use JSONPath syntax (e.g., $.user.id, $.items[0].name).
• Headers: Use the header name (e.g., Content-Type, Location).
• Full Body: Use * to extract the entire body.

Example Scenario

# @name create_user
POST https://api.example.com/users
Content-Type: application/json

{
  "username": "test_user",
  "role": "admin"
}

###

# @name login
POST https://api.example.com/login
Content-Type: application/json

{
  "username": "{{create_user.request.body.$.username}}",
  "password": "default_password"
}

###

# Use the token from login response
GET https://api.example.com/admin/dashboard
Authorization: Bearer {{login.response.body.$.token}}
X-User-Role: {{create_user.request.body.$.role}}

Conditional Execution

Complex test scenarios often require conditional logic. You might want to skip a cleanup step if the creation failed, or run specific tests only if a feature flag is enabled.

httprunner provides @dependsOn and @if directives.

# @name create_user
POST https://api.example.com/users
...

###

# Only run if create_user succeeded (HTTP 2xx)
# @dependsOn create_user
POST https://api.example.com/users/{{create_user.response.body.$.id}}/activate

###

# Only run if the user status is "active"
# @if create_user.response.body.$.status active
GET https://api.example.com/users/{{create_user.response.body.$.id}}

Assertions

No test is complete without verification. httprunner allows you to assert response status, headers, and body content directly in your .http file.

Basic Assertions

GET https://httpbin.org/json

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_BODY "slideshow"

Variable Substitution in Assertions

Crucially, variables are fully supported in assertions, allowing you to validate that a response matches input parameters or previous request data.

@expected_status=200
@user_id=123

# @name create_user
POST https://api.example.com/users
{ "id": "{{user_id}}" }

###

GET https://api.example.com/users/{{user_id}}

EXPECTED_RESPONSE_STATUS {{expected_status}}
EXPECTED_RESPONSE_BODY "{{user_id}}"
EXPECTED_RESPONSE_HEADERS "Location: /users/{{user_id}}"

This makes dynamic testing significantly easier, as you don’t need to hardcode expected values.

If any assertion fails, httprunner will report the test as failed and exit with a non-zero status code, which is essential for CI/CD pipelines.

Note: For requests that have assertions that expect failed responses (e.g., testing error handling), you can use EXPECTED_RESPONSE_STATUS to specify the expected failure status code (like 400 or 404). The “failed” request will no longer be flagged as failed, but instead will be validated against the expected status code and assertions.

Verbose Mode

When developing or debugging, you often need more insight into what httprunner is doing.

Use the --verbose flag to see detailed request and response information, including full headers and bodies. Add --pretty-json to format JSON payloads for readability.

httprunner tests.http --verbose --pretty-json

Discovery Mode

If you have tests scattered across multiple directories, use --discover to recursively find and execute all .http files.

httprunner --discover --verbose

Report Generation and Logging

For long-running tests or CI pipelines, console output isn’t enough. httprunner can generate structured reports and detailed logs.

Reports

Generate summary reports in Markdown (default) or HTML using the --report flag. HTML reports include responsive styling and dark mode support.

# Generate Markdown report
httprunner tests.http --report

# Generate HTML report
httprunner tests.http --report html

Logging

Use --log to save all console output to a file. This is useful for auditing and post-execution analysis.

httprunner tests.http --log execution.log

Export Mode

Sometimes you need the raw HTTP data for documentation or manual replay. The --export flag saves every request and response to individual, timestamped files.

httprunner tests.http --export

This will create files like GET_users_request_1738016400.log and GET_users_response_1738016400.log containing the exact payload sent and received.

Insecure HTTPS

When testing against local development environments or staging servers with self-signed certificates, SSL validation can be a blocker. Use --insecure to bypass these checks.

httprunner https://localhost:5001/api/tests.http --insecure

Note: Only use this in trusted environments!

Telemetry

httprunner collects anonymous usage data to help improve the tool. If you prefer to opt-out, you can disable it via a flag or environment variable.

# Disable via CLI
httprunner tests.http --no-telemetry

# Disable via Environment Variable
export HTTPRUNNER_TELEMETRY_OPTOUT=1
# or
export DO_NOT_TRACK=1

CI/CD Integration

Automating these tests in a CI/CD pipeline is straightforward. Since httprunner is available as a Docker image and a standalone binary, it fits easily into GitHub Actions or GitLab CI.

Here is an example GitHub Actions workflow:

name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install HTTP Runner
        run: snap install httprunner

      - name: Run API Tests
        run: tests/api.http --env staging --report markdown

Or, if you prefer installing the binary:

- name: Install HTTP Runner
  run: curl -fsSL https://christianhelle.com/httprunner/install | bash

- name: Run Tests
  run: httprunner tests/*.http --env staging --report html

This setup ensures that every change is validated against your API, providing fast feedback on regressions.

Conclusion

By combining the simplicity of .http files with the advanced features of httprunner, you can build a robust integration testing suite that lives right alongside your code. It’s version-controlled, easy to read, and powerful enough for complex scenarios involving authentication, chaining, and conditional logic.

Give it a try and let me know what you think!

The Critical Problem: HTTPS Certificate Validation

The primary driver for this migration was a blocking technical limitation in Zig’s standard library. The issue was simple but insurmountable: Zig’s HTTP client (std.http) cannot be configured to bypass certificate validation. This makes testing against development environments with self-signed certificates, a fundamental requirement for any serious HTTP testing tool, needlessly difficult, or impossible.

The Failed Solution

I explored integrating libcurl to work around this limitation, but the cross-platform compilation complexity proved prohibitive. Zig’s excellent cross-compilation support ironically became a liability when trying to integrate C libraries with complex build requirements across multiple platforms.

This wasn’t about preferring one language over another—the Zig implementation simply couldn’t meet basic requirements for development environment testing.

Migration Overview

The migration was fully AI assisted, comprehensive, touching every aspect of the project:

• 54 commits across the migration branch
• 3,419 lines added, 2,634 lines removed
• 54 files changed
• 12 core modules successfully ported
• 100% feature parity maintained

You can see the complete details in Pull Request #43.

Architecture: From Zig to Rust

Module Structure

The Rust implementation maintains a clean, modular architecture:

src/
├── main.rs              # Application entry point
├── cli.rs               # Command-line interface with clap
├── types.rs             # Core data structures
├── colors.rs            # Terminal color utilities
├── parser.rs            # HTTP file parsing
├── environment.rs       # Environment file loading
├── runner.rs            # HTTP request execution with reqwest
├── assertions.rs        # Response assertion validation
├── request_variables.rs # Request variable substitution
├── processor.rs         # Request processing pipeline
├── discovery.rs         # File discovery with walkdir
├── log.rs              # Logging functionality
└── upgrade.rs          # Self-update feature

Key Dependencies

The Rust ecosystem provided mature, battle-tested libraries for every requirement:

• clap: Modern command-line argument parsing with declarative macros
• reqwest: Full-featured HTTP client with TLS control
• colored: Cross-platform terminal colors
• serde_json: JSON parsing for environment files and chaining requests variables
• walkdir: Efficient directory traversal
• anyhow: Ergonomic error handling with context chaining

Feature Parity Verification

All features from the Zig implementation are fully supported in the Rust version:

Technical Improvements

Better Error Handling

Zig: Manual error unions and explicit error propagation

const result = try parseHttpFile(allocator, file_path);
defer result.deinit();

Rust: anyhow::Result with context chaining and detailed error messages

let result = parse_http_file(file_path)
    .context("Failed to parse HTTP file")?;

Type Safety and Memory Management

Zig: Explicit memory management with defer statements

const allocator = std.heap.page_allocator;
var list = try std.ArrayList(u8).initCapacity(allocator, 1024);
defer list.deinit();

Rust: Ownership system with compile-time guarantees

let mut list = Vec::with_capacity(1024);
// Automatically dropped when out of scope

HTTP Client Capabilities

Zig: Limited std.http with no TLS configuration options

Rust: Full TLS control, connection pooling, timeout management, and certificate validation options

let client = Client::builder()
    .danger_accept_invalid_certs(allow_insecure)
    .timeout(Duration::from_secs(30))
    .build()?;

This is the critical improvement that drove the entire migration. The reqwest library provides the flexibility needed for real-world testing scenarios.

CLI Parsing

Zig: Manual argument parsing with custom logic

Rust: Declarative clap with automatic help generation

#[derive(Parser)]
#[command(name = "httprunner")]
#[command(about = "Run .http files from the command line")]
struct Cli {
    #[arg(help = "HTTP files to process")]
    files: Vec<PathBuf>,

    #[arg(short, long, help = "Enable verbose output")]
    verbose: bool,
}

Migration Process

The migration followed a systematic, phased approach:

Phase 1: Core Infrastructure

• Set up Rust project structure with Cargo.toml
• Implemented build script for version generation
• Created core type definitions
• Added color utilities
• Built HTTP file parser

Phase 2: HTTP Execution

• Integrated reqwest for HTTP operations
• Implemented response assertions
• Added request variable substitution with JSONPath support
• Built environment file loader

Phase 3: CLI & Features

• Implemented clap-based CLI interface
• Added file discovery mode
• Implemented logging functionality
• Added self-update feature
• Created comprehensive request processor

Phase 4: Infrastructure

• Updated GitHub Actions workflows for Rust
• Migrated dev container to Rust toolchain
• Updated Docker configuration
• Modified release workflows for Rust binaries
• Added Snap packaging for Rust version

Phase 5: Cleanup & Documentation

• Removed Zig implementation from main branch
• Updated all documentation for Rust
• Added migration guides
• Updated README with Rust instructions
• Added Cargo/Crates.io installation instructions

Build System Comparison

The Rust tooling ecosystem provides a more comprehensive development experience with integrated testing, formatting, linting, and dependency management.

Installation: Now Even Easier

The Rust version adds a new installation method via Cargo:

# Install from crates.io
cargo install httprunner

All previous installation methods remain supported:

• Automated installation scripts (Linux/macOS/Windows)
• Snap Store: snap install httprunner
• Manual download from GitHub Releases
• Docker: docker pull christianhelle/httprunner
• Build from source: cargo build --release

The Zig Legacy

The original Zig implementation has been preserved in a separate repository: christianhelle/httprunner-zig. While it’s no longer actively maintained, it remains available as a historical reference and testament to Zig’s capabilities within its limitations.

The Zig version was an excellent learning experience, and I genuinely enjoyed working with the language. Zig’s simplicity, zero-cost abstractions, and explicit nature made it a pleasure to write. The limitation that forced this migration wasn’t a reflection on Zig as a language—it was simply a missing feature in the standard library’s HTTP implementation.

Lessons Learned

When to Rewrite

This migration taught me important lessons about when a rewrite is justified:

✅ Good reasons to rewrite:

• Blocking technical limitations that prevent core functionality
• Ecosystem maturity issues affecting long-term maintainability
• Fundamental architectural problems that can’t be incrementally improved

❌ Bad reasons to rewrite:

• Language preference or “grass is greener” syndrome
• Minor inconveniences that can be worked around
• Wanting to try new technologies without clear benefits

Language Selection Matters

While both Zig and Rust are excellent systems programming languages, their ecosystems have different maturity levels:

Zig Strengths:

• Simpler syntax and learning curve
• Excellent cross-compilation support
• No hidden control flow
• Explicit and predictable behavior

Rust Strengths:

• Mature ecosystem with battle-tested libraries
• Comprehensive standard library and crate ecosystem
• Strong compile-time guarantees via ownership system
• Extensive tooling (cargo, clippy, rustfmt)

For a production tool that needs to work reliably across various environments and scenarios, Rust’s ecosystem maturity proved decisive.

Performance Comparison

Both implementations are fast, but with different characteristics:

Binary Size:

• Zig: ~700KB (optimized for binary size)
• Rust (release): ~1.7MB (with all release build optimization and optimized for size)

Startup Time:

• Both: Instant (< 10ms)

Memory Usage:

• Both: Minimal (< 10MB for typical workloads)

HTTP Performance:

• Zig: Fast, but limited by std.http capabilities
• Rust: Fast with more features (connection pooling, better TLS)

The performance differences are negligible for this use case. The real benefits are in functionality and maintainability.

Moving Forward

The Rust version of HTTP File Runner is now the primary implementation and receives all active development. Future enhancements include:

• Request timeout configuration: Per-request and global timeout settings
• Response body filtering: JSONPath queries and XML parsing
• Parallel execution: Concurrent processing of non-chained requests for faster test suites
• Enhanced reporting: JSON, XML, and HTML output formats

Conclusion

Rewriting HTTP File Runner from Zig to Rust was driven by pragmatic necessity rather than preference. The inability to configure TLS certificate validation in Zig’s standard library was a blocking issue for a serious HTTP testing tool. While I enjoyed working with Zig and appreciated its design philosophy, the project needed the functionality and ecosystem maturity that Rust provides.

The migration maintained 100% feature parity while adding the critical capability to work with self-signed certificates in development environments. The Rust ecosystem’s mature libraries for HTTP, CLI parsing, and error handling made the rewrite straightforward and resulted in more maintainable code.

If you’re using the Zig version, I encourage you to try the Rust version:

cargo install httprunner

The tool remains fast, small, and cross-platform—but now it actually works in all the scenarios it needs to support. You can read more about the original Zig implementation in my previous post.

For more details on the migration, check out:

• Pull Request #43 - Complete migration details
• HTTP File Runner repository - Rust implementation
• HTTP File Runner (Zig) - Original implementation
• Documentation - Full user guide

The project continues to evolve, and I’m excited about the possibilities that Rust’s ecosystem enables for future enhancements.

If you’ve been using .http files to test your APIs manually in Visual Studio or other IDEs, HttpTestGen takes this workflow to the next level by automatically generating unit tests from those same files. This means you can design, test, and validate your APIs using the familiar .http syntax, then seamlessly integrate those tests into your automated test suite.

What is HttpTestGen?

HttpTestGen is a .NET source generator that reads .http files in your test projects and automatically generates corresponding xUnit or TUnit test methods at compile time. The tool supports a comprehensive range of HTTP operations and includes sophisticated assertion capabilities for validating API responses.

Key Features

HttpTestGen offers a rich set of features designed to make API testing both powerful and intuitive:

• Automatic Test Generation: Transform .http files into xUnit or TUnit test code at compile time
• Rich HTTP Support: Parse GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, and TRACE methods
• Header Processing: Full support for HTTP headers including custom headers
• Request Bodies: Support for JSON, XML, and text request bodies
• Response Assertions: Validate expected status codes and response headers
• Multiple Test Frameworks: Generate tests for xUnit and TUnit
• Source Generator: Zero-runtime overhead with compile-time code generation
• IDE Integration: Works seamlessly with existing .http files in your IDE

Installation

Getting started with HttpTestGen is straightforward. The tool is available as NuGet packages for both xUnit and TUnit frameworks.

xUnit Generator

For xUnit-based projects, add the following package reference to your test project:

<PackageReference Include="HttpTestGen.XunitGenerator" Version="1.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

TUnit Generator

For TUnit-based projects, use this package reference:

<PackageReference Include="HttpTestGen.TUnitGenerator" Version="1.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

The PrivateAssets="all" ensures that the source generator is only used at compile time and doesn’t become a runtime dependency of your application.

Creating .http Files in Visual Studio

Visual Studio provides excellent support for .http files, making it easy to design and test your APIs interactively before converting them into automated tests.

Basic .http File Syntax

Create a .http file in your test project with HTTP requests. Here’s an example covering common scenarios:

# Simple GET request
GET https://api.example.com/users

# GET request with headers
GET https://api.example.com/users/123
Accept: application/json
Authorization: Bearer your-token-here

# POST request with JSON body
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

# Request with expected status code
GET https://api.example.com/nonexistent
EXPECTED_RESPONSE_STATUS 404

# Request with expected response headers
GET https://api.example.com/data
EXPECTED_RESPONSE_HEADER content-type: application/json
EXPECTED_RESPONSE_HEADER x-custom-header: custom-value

Visual Studio Integration

When working with .http files in Visual Studio, you can:

1. Test manually: Use the “Send Request” button to execute requests directly from the editor
2. View responses: See formatted JSON, XML, and text responses inline
3. Debug requests: Inspect headers, status codes, and response times
4. Environment support: Use variables for different environments (development, staging, production)

Assertion Keywords

HttpTestGen implements powerful assertion keywords that allow you to validate API responses automatically. These assertions are embedded directly in your .http files and become part of the generated test code.

Status Code Assertions

Use EXPECTED_RESPONSE_STATUS to validate HTTP status codes:

# Test successful response
GET https://api.example.com/users
EXPECTED_RESPONSE_STATUS 200

# Test not found scenario
GET https://api.example.com/notfound
EXPECTED_RESPONSE_STATUS 404

# Test authentication failure
GET https://api.example.com/protected
Authorization: Bearer invalid-token
EXPECTED_RESPONSE_STATUS 401

Header Assertions

Use EXPECTED_RESPONSE_HEADER to validate response headers:

# Validate content type and caching headers
GET https://api.example.com/api/data
EXPECTED_RESPONSE_HEADER content-type: application/json
EXPECTED_RESPONSE_HEADER cache-control: no-cache

# Validate custom security headers
GET https://api.example.com/secure-endpoint
EXPECTED_RESPONSE_HEADER x-security-token: required
EXPECTED_RESPONSE_HEADER x-rate-limit-remaining: *

Generated Test Code

The source generator automatically creates test methods from your .http files. The generated code is clean, readable, and follows testing best practices.

xUnit Output Example

For the .http file examples above, HttpTestGen would generate:

public class ApiTestsXunitTests
{
    [Xunit.Fact]
    public async Task get_api_example_com_0()
    {
        var sut = new System.Net.Http.HttpClient();
        var response = await sut.GetAsync("https://api.example.com/users");
        Xunit.Assert.True(response.IsSuccessStatusCode);
    }

    [Xunit.Fact]
    public async Task get_api_example_com_1()
    {
        var sut = new System.Net.Http.HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Get, "https://api.example.com/users/123");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("Authorization", "Bearer your-token-here");
        
        var response = await sut.SendAsync(request);
        Xunit.Assert.True(response.IsSuccessStatusCode);
    }

    [Xunit.Fact]
    public async Task post_api_example_com_2()
    {
        var sut = new System.Net.Http.HttpClient();
        var content = new StringContent("{\"name\":\"John Doe\",\"email\":\"john@example.com\"}", 
            System.Text.Encoding.UTF8, "application/json");
        
        var response = await sut.PostAsync("https://api.example.com/users", content);
        Xunit.Assert.True(response.IsSuccessStatusCode);
    }

    [Xunit.Fact]
    public async Task get_api_example_com_3()
    {
        var sut = new System.Net.Http.HttpClient();
        var response = await sut.GetAsync("https://api.example.com/nonexistent");
        Xunit.Assert.Equal(404, (int)response.StatusCode);
    }

    [Xunit.Fact]
    public async Task get_api_example_com_4()
    {
        var sut = new System.Net.Http.HttpClient();
        var response = await sut.GetAsync("https://api.example.com/data");
        Xunit.Assert.True(response.IsSuccessStatusCode);
        Xunit.Assert.True(response.Headers.GetValues("content-type").Contains("application/json"));
        Xunit.Assert.True(response.Headers.GetValues("x-custom-header").Contains("custom-value"));
    }
}

Generated Test Features

The generated tests include:

• Proper HTTP client usage: Each test method creates and uses an HttpClient instance
• Header handling: Request headers are properly added to HTTP requests
• Content management: Request bodies are converted to appropriate HttpContent types
• Assertion integration: Expected status codes and headers become proper test assertions
• Async/await patterns: All HTTP operations use proper async patterns

Project Integration

Integrating HttpTestGen into your project is seamless and requires minimal configuration.

Example Project Structure

MyProject.Tests/
├── MyProject.Tests.csproj
├── api-tests.http
├── user-tests.http
└── integration-tests.http

The source generator will automatically create corresponding test classes:

• api-tests.http → ApiTestsXunitTests or ApiTestsTests (TUnit)
• user-tests.http → UserTestsXunitTests or UserTestsTests (TUnit)
• integration-tests.http → IntegrationTestsXunitTests or IntegrationTestsTests (TUnit)

Development Workflow

The typical development flow with HttpTestGen is:

1. Design your API using .http files in your IDE
2. Test manually using REST Client extensions or Visual Studio’s built-in HTTP client
3. Add assertions for expected behavior using the assertion keywords
4. Build project to generate automated tests
5. Run tests in CI/CD pipeline

Running Tests

Once your project is built, you can run the generated tests using standard .NET testing tools:

# Run all tests
dotnet test

# Run tests with verbose output
dotnet test --logger:console;verbosity=detailed

# Run specific test class
dotnet test --filter "ApiTestsXunitTests"

Advanced Features

HttpTestGen supports several advanced features for complex testing scenarios.

Multiple Request Bodies

The tool supports various content types for request bodies:

# JSON body
POST https://api.example.com/data
Content-Type: application/json

{
  "key": "value"
}

# XML body  
POST https://api.example.com/data
Content-Type: application/xml

<root>
  <item>value</item>
</root>

# Plain text body
POST https://api.example.com/data
Content-Type: text/plain

This is plain text content

Comments and Documentation

Use # for comments in your .http files to document your tests:

# This tests user authentication
POST https://api.example.com/auth/login
Content-Type: application/json

{
  "username": "testuser",
  "password": "testpass"
}

# Verify successful login returns token
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADER content-type: application/json

Multiple Requests

Separate multiple requests with blank lines or comments:

GET https://api.example.com/users

# Test user creation
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Test User"
}

# Test user deletion
DELETE https://api.example.com/users/123

Best Practices

Organization and Structure

• Organize by feature: Create separate .http files for different API endpoints or features
• Use descriptive comments: Document what each request tests
• Add assertions: Always include expected status codes and important headers
• Environment variables: Use your IDE’s environment variable support for different environments
• Version control: Commit your .http files alongside your code

Testing Strategies

Unit Tests vs Integration Tests:

• Unit Tests: Test individual endpoints with mocked dependencies
• Integration Tests: Test complete API flows with real HTTP calls
• Contract Tests: Verify API contracts match expectations

Assertion Patterns:

# Success scenarios
GET https://api.example.com/users
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADER content-type: application/json

# Error scenarios  
GET https://api.example.com/users/999999
EXPECTED_RESPONSE_STATUS 404

# Authentication scenarios
GET https://api.example.com/protected
Authorization: Bearer invalid-token
EXPECTED_RESPONSE_STATUS 401

Performance Considerations

HttpTestGen is designed for optimal performance:

• Compile-time generation: Zero runtime overhead
• Incremental builds: Only regenerates when .http files change
• Parallel execution: Generated tests can run in parallel
• Memory efficient: No reflection or dynamic compilation at runtime

Integration with Popular Tools

Visual Studio Code

HttpTestGen works seamlessly with the REST Client extension for Visual Studio Code, allowing you to design and test APIs interactively before generating automated tests.

JetBrains IDEs

The tool is compatible with the built-in HTTP client in IntelliJ IDEA, WebStorm, and Rider, providing a consistent experience across different development environments.

CI/CD Integration

Generated tests integrate naturally with CI/CD pipelines:

# Example GitHub Actions workflow
- name: Run API Tests
  run: dotnet test --filter "HttpTestGen" --logger trx

Conclusion

HttpTestGen represents a significant step forward in .NET API testing, bridging the gap between manual API testing and automated test suites. By leveraging the familiar .http file format that developers already use for interactive API testing, HttpTestGen eliminates the friction between designing APIs and testing them comprehensively.

The tool’s source generator approach ensures zero runtime overhead while providing powerful assertion capabilities that validate not just connectivity, but the correctness of API responses. Whether you’re building microservices, REST APIs, or integration tests, HttpTestGen fits naturally into your development workflow.

The combination of Visual Studio’s excellent .http file support and HttpTestGen’s automatic test generation creates a seamless experience from API design to automated testing. Your .http files become living documentation of your API contracts while simultaneously serving as comprehensive test suites.

Give HttpTestGen a try in your next .NET project and experience how it can streamline your API testing workflow. The tool is open source and available on GitHub, where you can contribute, report issues, or explore the implementation details.

Whether you’re just getting started with API testing or looking to improve your existing testing strategy, HttpTestGen provides a powerful, lightweight solution that grows with your project’s needs.

This project started as a learning exercise to explore the Zig programming language’s capabilities. In a previous post, entitled Generate .http files from OpenAPI specifications, I wrote about HTTP File Generator, a tool that generates .http files from OpenAPI specifications. It felt natural to create a companion tool that could execute these generated files outside an IDE. The combination of these two tools creates a complete workflow: generate HTTP files from your API specifications, then run them from the command line for testing and validation.

What is HTTP File Runner?

HTTP File Runner is a simple yet powerful tool that reads .http files (the same format used by popular IDEs like Visual Studio Code, JetBrains IDEs, and Visual Studio 2022) and executes the HTTP requests defined within them. It’s designed to be fast, reliable, and developer-friendly.

The beauty of this approach lies in its simplicity. .http files are plain text files that can be generated, version-controlled, shared between team members, and executed across different environments. These files are human-readable and can be edited with any text editor. This makes them perfect for documentation, on-boarding new team members, and ensuring consistency across development environments.

Key Features

The tool comes packed with features that make API testing a breeze, each designed to address common pain points in API development and testing workflows:

• Parse and execute HTTP requests from .http files - The core functionality that reads the standard HTTP file format and executes requests sequentially
• Support for multiple files - Run several .http files in a single command, perfect for organizing tests by feature or service
• Discovery mode - Recursively find and run all .http files in a directory tree, ideal for comprehensive test suites
• Verbose mode for detailed request and response information - See exactly what’s being sent and received, invaluable for debugging
• Logging mode to save all output to a file for analysis and reporting - Essential for CI/CD pipelines and audit trails
• Color-coded output (green for success, red for failure) - Immediate visual feedback on test results
• Summary statistics showing success/failure counts per file and overall - Quick overview of test suite health
• Support for various HTTP methods (GET, POST, PUT, DELETE, PATCH) - Covers all standard REST operations
• Variables support with substitution in URLs, headers, and request bodies - Enables dynamic and reusable test scenarios
• Response assertions for status codes, body content, and headers - Automated validation of API responses

These features work together to create a comprehensive testing solution that scales from simple smoke tests to complex integration test suites. The combination of batch processing, detailed reporting, and assertion capabilities makes it suitable for both development-time testing and production monitoring.

Why Zig?

Choosing Zig for this project was intentional. This started as a learning exercise to explore the Zig programming language. In fact, choosing Zig came before even deciding what to build. I primarily work with higher-level languages like C# in my day job, and I wanted to understand what Zig brings to the table. The decision was an excellent choice for several compelling reasons:

Performance

Zig compiles to highly optimized native code without the overhead of a runtime or garbage collector. This means HTTP File Runner starts instantly and processes requests with minimal memory footprint.

The resulting binary is small (under 2MB), starts instantly, and handles network operations efficiently. The cross-platform support means teams can use the same tool regardless of their development environment, reducing friction and improving consistency.

Memory management

Zig gives you explicit control over memory allocation and deallocation (similar to C/C++), but with helpful features to reduce errors. One standout is Zig’s defer statement, which ensures resources are released when a scope exits—making it easy to prevent memory leaks and resource leaks. While Zig does not provide full memory safety guarantees, its compile-time checks, clear ownership model, and defer help you write reliable low-level code more safely than traditional C.

Cross-platform

Zig’s excellent cross-compilation support made it trivial to build binaries for Linux, MacOS, and Windows from a single codebase. The build system handles platform-specific details seamlessly, which is essential for a tool that needs to work everywhere developers do.

Simple syntax

Zig’s philosophy of “no hidden control flow” means the code does exactly what it appears to do. This makes the codebase easier to understand, debug, and maintain. Coming from higher-level languages, I appreciated how Zig forces you to be explicit about your intentions.

No runtime

Zero-cost abstractions and no garbage collector mean predictable performance characteristics. This is particularly important for a command-line tool that might be called thousands of times in automated testing scenarios.

Great editor support

Zig’s Language Server Protocol (LSP) implementation provides excellent code completion, diagnostics, and navigation features in editors like Visual Studio Code or Neovim. This made development smooth and productive, with real-time feedback and powerful refactoring tools available out of the box.

Learning value

As someone whose day job is working in managed languages, exploring manual memory management and system-level programming concepts in Zig provided valuable insights.

Compared to Rust, I found Zig’s learning curve to be less steep, and more fun to write. Zig offers a straightforward syntax which made it easier to grasp the core concepts quickly. While both languages provide low-level control and strong performance, Zig’s simplicity and explicitness helped me become productive faster, making it an appealing choice for systems programming projects like this one.

The Zig Zen

Zig’s development philosophy, known as “The Zen of Zig,” states the following:

• Communicate intent precisely.
• Edge cases matter.
• Favor reading code over writing code.
• Only one obvious way to do things.
• Runtime crashes are better than bugs.
• Compile errors are better than runtime crashes.
• Incremental improvements.
• Avoid local maximums.
• Reduce the amount one must remember.
• Focus on code rather than style.
• Resource allocation may fail; resource deallocation must succeed.
• Memory is a resource.
• Together we serve the users.

Installation

Getting started is incredibly easy. The tool provides multiple installation options to suit different preferences and environments. I’ve focused on making the installation process as frictionless as possible, recognizing that developers often need to get tools up and running quickly.

Quick Install (Recommended)

The fastest way to get started is using the automated installation scripts. These scripts handle platform detection, architecture identification, and PATH configuration automatically:

Linux/MacOS:

curl -fsSL https://christianhelle.com/httprunner/install | bash

Windows (PowerShell):

irm https://christianhelle.com/httprunner/install.ps1 | iex

These scripts will automatically:

• Detect your operating system and CPU architecture
• Download the appropriate binary from the latest GitHub release
• Install it to a standard location (/usr/local/bin on Unix-like systems, $HOME/.local/bin as fallback)
• Optionally add the installation directory to your PATH
• Verify the installation was successful

Other Installation Methods

For users who prefer different installation approaches or have specific requirements:

• Snap Store: snap install httprunner - Great for Ubuntu and other snap-enabled distributions, provides automatic updates
• Manual Download: Download from GitHub Releases - Full control over installation location and process
• Docker: docker pull christianhelle/httprunner - Perfect for containerized environments or when you don’t want to install binaries locally
• Build from source: Clone the repo and run zig build - For developers who want to customize the build or contribute to the project

Each method has its advantages: Snap provides automatic updates, manual download gives you full control, Docker ensures isolation, and building from source allows customization. Choose the method that best fits your workflow and security requirements.

Usage Examples

Here are some common usage patterns that demonstrate the tool’s flexibility and power. These examples progress from simple single-file execution to complex batch processing scenarios:

# Run a single .http file
httprunner api-tests.http

# Run with verbose output
httprunner api-tests.http --verbose

# Run multiple files
httprunner auth.http users.http posts.http

# Discover and run all .http files recursively
httprunner --discover

# Save output to a log file
httprunner api-tests.http --log results.txt

# Combine verbose mode with logging
httprunner --discover --verbose --log full-test-report.log

Real-World Scenarios

Development Workflow: During development, you might run httprunner --discover --verbose to execute all tests in your project and see detailed output for debugging.

CI/CD Integration: In your build pipeline, use httprunner --discover --log test-results.log to run all tests and capture results for build reports.

Environment Testing: When deploying to a new environment, run httprunner health-checks.http --env production --log deployment-validation.log to verify everything is working correctly.

Performance Monitoring: Set up automated runs with httprunner monitoring.http --log performance.log to track API performance over time.

HTTP File Format

The tool supports the well known .http file format:

# Comments start with #

# Basic GET request
GET https://api.github.com/users/octocat

# Request with headers
GET https://httpbin.org/headers
User-Agent: HttpRunner/1.0
Accept: application/json

# POST request with body
POST https://httpbin.org/post
Content-Type: application/json

{
  "name": "test",
  "value": 123
}

Variables and Environment Support

One of the most powerful features is the comprehensive variable support system, which enables you to create flexible, reusable test suites that work across different environments. This feature addresses one of the biggest pain points in API testing: managing different configurations for development, staging, and production environments.

Basic Variable Usage

Variables are defined using the @ syntax and referenced with double curly braces:

@hostname=localhost
@port=8080
@baseUrl=https://:

GET /api/users
Authorization: Bearer 

Advanced Variable Composition

Variables can be composed of other variables, allowing you to build complex configurations incrementally:

@protocol=https
@hostname=api.example.com
@port=443
@version=v1
@baseUrl=://:/

# Now you can use the composed URL
GET /users
GET /posts
GET /comments

Environment Configuration Files

For managing different environments, you can create an http-client.env.json file with environment-specific values:

{
  "dev": {
    "HostAddress": "https://localhost:44320",
    "ApiKey": "dev-api-key-123",
    "Environment": "development"
  },
  "staging": {
    "HostAddress": "https://staging.example.com",
    "ApiKey": "staging-api-key-456",
    "Environment": "staging"
  },
  "prod": {
    "HostAddress": "https://api.example.com",
    "ApiKey": "prod-api-key-789",
    "Environment": "production"
  }
}

Then specify the environment when running tests:

httprunner api-tests.http --env dev

This approach allows you to maintain a single set of test files while easily switching between different environments. The variable override behavior is intelligent: environment variables are loaded first, then any variables defined in the .http file override them, giving you both flexibility and control.

Response Assertions

The response assertion system is one of HTTP File Runner’s most powerful features, transforming it from a simple request executor into a comprehensive API testing framework. This system enables you to validate not just that your API responds, but that it responds correctly with the expected data, status codes, and headers. By incorporating assertions into your .http files, you can create robust test suites that catch regressions, validate API contracts, and ensure your services behave correctly across different environments.

Understanding Assertion Philosophy

HTTP File Runner’s assertion system is designed around the principle of explicit validation. Rather than assuming that any response is acceptable, assertions force you to define what constitutes a successful interaction with your API. This approach catches subtle bugs that might otherwise go unnoticed, such as:

• APIs returning 200 status codes with error messages in the body
• Correct data with unexpected content types or encoding
• Missing or incorrect security headers
• Performance regressions indicated by unexpected response patterns

Types of Assertions

Status Code Assertions

Status code assertions are the foundation of API testing, ensuring your endpoints return the correct HTTP status codes for different scenarios:

# Test successful resource retrieval
GET https://httpbin.org/status/200
EXPECTED_RESPONSE_STATUS 200

# Test resource not found scenario
GET https://httpbin.org/status/404
EXPECTED_RESPONSE_STATUS 404

Status code assertions are particularly valuable for testing error conditions and edge cases. You can verify that your API correctly returns 400 for bad requests, 401 for unauthorized access, 403 for forbidden operations, and 404 for missing resources.

Response Body Assertions

Response body assertions validate the actual content returned by your API. These assertions use substring matching, making them flexible enough to work with various response formats while being specific enough to catch content errors:

# Test JSON response content
GET https://httpbin.org/json
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "slideshow"
EXPECTED_RESPONSE_BODY "Sample Slide Show"

# Test API response structure
GET https://jsonplaceholder.typicode.com/users/1
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "Leanne Graham"
EXPECTED_RESPONSE_BODY "@hildegard.org"

Body assertions are case-sensitive and look for exact substring matches. This approach allows you to validate specific field values in JSON responses, error messages, HTML content, XML elements, and plain text responses.

Response Header Assertions

Header assertions validate the metadata returned with your API responses. These are crucial for testing security headers, content types, caching directives, and custom application headers:

# Test content type and security headers
GET https://httpbin.org/json
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"

# Test custom application headers
POST https://httpbin.org/post
Content-Type: application/json

{"test": "data"}

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_HEADERS "Server: gunicorn"

Header assertions use substring matching on the full header line (including both name and value). This flexibility allows you to validate exact header values, check for header presence, test multiple values for the same header, and verify security and compliance headers.

Advanced Assertion Patterns

Comprehensive API Endpoint Testing

Here’s an example of thoroughly testing a user management API endpoint:

# Test user creation with comprehensive validation
POST https://api.example.com/users
Content-Type: application/json
Authorization: Bearer 

{
  "name": "Christian Helle",
  "email": "christian.helle@example.com",
  "role": "user"
}

EXPECTED_RESPONSE_STATUS 201
EXPECTED_RESPONSE_BODY "Christian Helle"
EXPECTED_RESPONSE_BODY "christian.helle@example.com"
EXPECTED_RESPONSE_BODY "\"id\":"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
EXPECTED_RESPONSE_HEADERS "Location: /users/"

###

# Verify user is deleted properly
DELETE https://api.example.com/users/
Authorization: Bearer 

EXPECTED_RESPONSE_STATUS 204

###

# Confirm user no longer exists
GET https://api.example.com/users/
Authorization: Bearer 

EXPECTED_RESPONSE_STATUS 404
EXPECTED_RESPONSE_BODY "User not found"

Error Condition Testing

Testing error conditions is just as important as testing success scenarios:

# Test validation errors
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "",
  "email": "invalid-email"
}

EXPECTED_RESPONSE_STATUS 400
EXPECTED_RESPONSE_BODY "validation error"
EXPECTED_RESPONSE_BODY "name is required"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"

###

# Test authentication errors
GET https://api.example.com/users
Authorization: Bearer invalid-token

EXPECTED_RESPONSE_STATUS 401
EXPECTED_RESPONSE_BODY "unauthorized"
EXPECTED_RESPONSE_HEADERS "WWW-Authenticate: Bearer"

Assertion Execution and Behavior

Processing Order and Logic

When HTTP File Runner encounters assertions in a .http file, it follows a specific execution pattern:

1. Request Execution: The HTTP request is sent normally, following all redirects and handling authentication
2. Response Capture: The complete response is captured, including status code, headers, and body
3. Assertion Evaluation: Each assertion is evaluated in the order it appears in the file
4. Result Aggregation: All assertion results are collected and reported
5. Request Status Determination: The request is marked as successful only if ALL assertions pass

Enhanced Logging and Reporting

When assertions are present, HTTP File Runner automatically enables enhanced logging, even in non-verbose mode:

🚀 HTTP File Runner - Processing file: .\tests\user-api.http
==================================================
Found 3 HTTP request(s)

✅ POST https://api.example.com/users - Status: 201 - 245ms
   ✅ Status assertion passed: 201
   ✅ Body assertion passed: "Christian Helle"
   ✅ Body assertion passed: "christian.helle@example.com"
   ✅ Header assertion passed: "Content-Type: application/json"
   ✅ Header assertion passed: "Location: /users/"

❌ GET https://api.example.com/users/invalid - Status: 404 - 123ms
   ✅ Status assertion passed: 404
   ❌ Body assertion failed: Expected "user not found" but got "Resource not found"
   ✅ Header assertion passed: "Content-Type: application/json"

✅ DELETE https://api.example.com/users/123 - Status: 204 - 156ms
   ✅ Status assertion passed: 204
   ✅ Header assertion passed: "X-Deleted-At:"

==================================================
File Summary: 2/3 requests succeeded
Total Assertions: 9 passed, 1 failed

Verbose Mode Enhancement

In verbose mode, HTTP File Runner provides even more detailed information about assertion evaluation:

🚀 HTTP File Runner - Processing file: .\tests\detailed-test.http
==================================================

📤 Request: POST https://api.example.com/users
Headers:
  Content-Type: application/json
  Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Body:
{
  "name": "Christian Helle",
  "email": "christian.helle@example.com"
}

📥 Response: 201 Created (245ms)
Headers:
  Content-Type: application/json; charset=utf-8
  Location: /users/12345
  X-RateLimit-Remaining: 99
  Content-Length: 156

Body:
{
  "id": 12345,
  "name": "Christian Helle",
  "email": "christian.helle@example.com",
  "created_at": "2025-06-21T10:30:00Z",
  "role": "user"
}

🔍 Assertion Results:
   ✅ EXPECTED_RESPONSE_STATUS 201
      Expected: 201, Actual: 201 ✓

   ✅ EXPECTED_RESPONSE_BODY "Christian Helle"
      Found substring "Christian Helle" in response body ✓

   ✅ EXPECTED_RESPONSE_BODY "christian.helle@example.com"
      Found substring "christian.helle@example.com" in response body ✓

   ✅ EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"
      Found header match "Content-Type: application/json" ✓

   ✅ EXPECTED_RESPONSE_HEADERS "Location: /users/"
      Found header match "Location: /users/" ✓

✅ Request completed successfully - All assertions passed

Best Practices for Assertion

Start Simple, Build Complex

Begin with basic status code assertions and gradually add more specific validations:

# Level 1: Basic connectivity
GET https://api.example.com/health
EXPECTED_RESPONSE_STATUS 200

# Level 2: Add content validation
GET https://api.example.com/health
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "healthy"

# Level 3: Full contract validation
GET https://api.example.com/health
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "healthy"
EXPECTED_RESPONSE_BODY "\"uptime\":"
EXPECTED_RESPONSE_BODY "\"version\":"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"

Use Specific but Resilient Assertions

Make your assertions specific enough to catch real issues, but resilient enough to not break on minor changes:

# Good: Validates presence of key fields
EXPECTED_RESPONSE_BODY "\"id\":"
EXPECTED_RESPONSE_BODY "\"name\":"
EXPECTED_RESPONSE_BODY "\"email\":"

# Avoid: Too specific, breaks on formatting changes
EXPECTED_RESPONSE_BODY "  \"id\": 123,"

Test Both Success and Failure Scenarios

Comprehensive testing includes validating that your API fails correctly:

# Test success case
POST https://api.example.com/login
Content-Type: application/json

{"username": "valid@example.com", "password": "correct"}

EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "\"token\":"

###

# Test failure case
POST https://api.example.com/login
Content-Type: application/json

{"username": "invalid@example.com", "password": "wrong"}

EXPECTED_RESPONSE_STATUS 401
EXPECTED_RESPONSE_BODY "invalid credentials"

Integration with Development Workflows

Pre-commit Testing

Use assertions in pre-commit hooks to catch API regressions before they reach version control:

# In your pre-commit script
httprunner tests/api-contracts.http --verbose
if [ $? -ne 0 ]; then
    echo "API contract tests failed. Commit blocked."
    exit 1
fi

Environment Validation

After deployments, run assertion-heavy test suites to validate the new environment:

# Validate staging deployment
httprunner tests/smoke-tests.http --env staging --log staging-validation.log

# Validate production deployment
httprunner tests/critical-paths.http --env production --log prod-validation.log

Performance and Regression Testing

Combine assertions with regular execution to catch both functional and performance regressions:

# This request should complete quickly and return valid data
GET https://api.example.com/users?page=1&limit=10
EXPECTED_RESPONSE_STATUS 200
EXPECTED_RESPONSE_BODY "\"users\":"
EXPECTED_RESPONSE_BODY "\"total\":"
EXPECTED_RESPONSE_HEADERS "Content-Type: application/json"

# The timing information in the output helps track performance trends

This comprehensive assertion system ensures that your API tests are thorough, reliable, and provide meaningful feedback when things go wrong. By incorporating detailed assertions into your HTTP files, you create living documentation of your API contracts while building robust test suites that catch issues early in the development cycle.

Logging and CI/CD Integration

The logging feature makes this tool perfect for CI/CD pipelines and automated testing scenarios. Modern software development relies heavily on automation, and HTTP File Runner’s logging capabilities are designed to integrate seamlessly into these workflows.

Logging Options

The --log flag provides several options for capturing test results:

# Generate test reports for build systems
httprunner --discover --log test_report_$(date +%Y%m%d_%H%M%S).log

# Daily API health checks
httprunner health-checks.http --verbose --log daily_health_check.log

Integration Scenarios

Build Pipeline Integration: Configure your CI/CD system to run HTTP File Runner as part of the build process. The tool’s exit codes and log files provide everything needed for build status determination and result reporting.

Deployment Validation: After deploying to a new environment, automatically run a suite of health check requests to verify that all services are responding correctly.

Monitoring and Alerting: Set up scheduled runs of critical API tests, with log files feeding into monitoring systems that can alert on failures or performance degradation.

Documentation and Reporting: The verbose logging mode captures complete request/response cycles, making it easy to generate API documentation or troubleshooting guides from actual test runs.

Log File Benefits

Log files preserve:

• Complete terminal output including colors and emojis
• Detailed HTTP request and response information (when using --verbose)
• Success/failure indicators and summary statistics
• Error messages and network diagnostics
• Execution timestamps and duration metrics

This comprehensive logging makes HTTP File Runner suitable not just for testing, but for API monitoring, documentation generation, and troubleshooting production issues.

Output Examples

The tool provides beautiful, color-coded output:

🚀 HTTP File Runner - Processing file: .\examples\simple.http
==================================================
Found 4 HTTP request(s)

✅ GET https://httpbin.org/status/200 - Status: 200 - 557ms
❌ GET https://httpbin.org/status/404 - Status: 404 - 542ms
✅ GET https://api.github.com/zen - Status: 200 - 85ms
✅ GET https://jsonplaceholder.typicode.com/users/1 - Status: 200 - 91ms

==================================================
File Summary: 3/4 requests succeeded

What’s Next?

I’m continuously improving the tool based on user feedback and real-world usage patterns. The roadmap includes several exciting enhancements that will further enhance its capabilities:

Planned Enhancements

• Request timeout configuration - Configurable timeouts per request or globally, essential for testing APIs with varying response times or unreliable networks.

• JSON response formatting - Pretty-printing and syntax highlighting for JSON responses, making it easier to read and debug API responses.

• Export results to different formats - JSON, XML, CSV, and HTML reports for integration with various reporting and analysis tools.

• Parallel execution - Option to run multiple requests concurrently for faster test suite execution.

Conclusion

HTTP File Runner represents my exploration into newer programming languages with Zig while solving a real-world problem that affects developers daily. What started as a learning exercise to understand Zig evolved into a genuinely useful tool that complements my existing HTTP File Generator project.

Building HTTP File Runner in Zig has been an exercise in balancing performance with usability.

The modular code structure makes the project maintainable and extensible. Each component, from HTTP parsing to response validation, is cleanly separated, making it easy to add new features or modify existing behavior.

Give it a try and let me know what you think! If you find it useful, consider starring the repository or sharing it with fellow developers.

Why Rust?

To be completely honest, this project started as a learning adventure. I’ve been wanting to dive deeper into Rust for a while now, attracted by all the buzz around its performance and memory safety guarantees. But I needed a real-world project that would push me beyond the typical “hello world” tutorials.

The turning point came when I discovered the Azure DevOps Rust API - a beautifully crafted library that was auto-generated from OpenAPI specifications. It was like finding the perfect building blocks for my vision. Here was a chance to combine my frustration with existing tooling, my desire to learn Rust, and a solid foundation to build upon.

As I dove into development, I was amazed by Rust’s promises coming to life. What emerged was azdocli - a tool that delivers near-instant command execution, uses minimal memory, and compiles to a single static binary with zero dependencies. No more waiting for Python environments to initialize or dealing with complex dependency chains. Just download one file and you’re ready to go.

Key Features

• Lightning fast: Commands execute in milliseconds.
• Cross-platform: Works on Windows, macOS, and Linux.
• No dependencies: Just download the binary and run.
• Simple authentication: Supports Personal Access Tokens (PAT) for secure authentication.
• Default project management: Set a default project to avoid specifying --project for every command.
• Repository Management: List, create, delete, clone, view, and manage pull requests in repositories.
• Pipeline Management: List pipelines, view runs, show details, and trigger new builds.
• Board Management: Create, read, update, and delete work items (bugs, tasks, user stories, features, epics).
• Parallel operations: Clone multiple repositories simultaneously with configurable concurrency.
• Easy scripting: Designed for automation and CI/CD workflows with --yes flags to skip confirmations.

Getting Started

Installation Options

There are different ways to install azdocli:

Quick Install Scripts (Recommended)

Linux and macOS:

curl -sSL https://christianhelle.com/azdocli/install | bash

Windows (PowerShell):

iwr -useb https://christianhelle.com/azdocli/install.ps1 | iex

These one-liner commands will automatically download and install the latest release for your platform.

From crates.io (Requires Rust)

cargo install azdocli

From GitHub Releases

1. Download the latest release from the GitHub releases page.
   • Windows: windows-x64.zip or windows-arm64.zip
   • macOS: macos-x64.zip or macos-arm64.zip
   • Linux: linux-x64.zip or linux-arm64.zip
2. Extract the binary and add it to your PATH.
3. Make the binary executable (chmod +x ado on Unix).

Authentication Setup

Before using the CLI, you need to create a Personal Access Token (PAT) in Azure DevOps:

1. Navigate to Azure DevOps:
   • Sign in to your Azure DevOps organization (https://dev.azure.com/{yourorganization})
   • Click on your profile picture in the top right corner
   • Select Personal Access Tokens
2. Create New Token:
   • Click + New Token
   • Enter a descriptive name (e.g., “azdocli-token”)
   • Select your organization
   • Set expiration date (recommended: 90 days or less)
3. Configure Required Scopes:
   • Code: Read & write (for repository operations)
   • Build: Read & execute (for pipeline operations)
   • Work Items: Read & write (for board operations)
   • Project and Team: Read (for project operations)
4. Save Your Token: Copy the token immediately and store it securely - it won’t be shown again.

Initial Setup

# Login with your Personal Access Token
azdocli login
# You'll be prompted for:
# - Organization name (e.g., "mycompany" from https://dev.azure.com/mycompany)
# - Personal Access Token (the PAT you created above)

# Set a default project (optional but recommended)
azdocli project MyProject

The “Aha!” Moment: Real-World Performance

Let me share a story that perfectly illustrates why I built this tool. A couple of months ago, I was working on a project that required cloning hundreds of repositories from different Azure DevOps projects. With the official CLI and some scripting, this was a painful process - each repository clone command took several seconds to even start, and I had to run them one by one.

With azdocli, I can now do this:

azdocli repos clone --parallel --concurrency 32 --yes

What used to take me 20 minutes of building a script and babysitting individual commands now completes in a few seconds, running unattended in the background while I do something else. That’s the kind of time savings that actually changes how you work.

Behind the Scenes: Development Stories

The Default Project Revelation

One of my favorite features didn’t come from grand planning - it emerged from pure frustration. During development, I found myself constantly typing --project MyProject for every single command. After the hundredth time, I thought “there has to be a better way.”

That’s when I implemented the default project feature:

# Set it once
azdocli project MyDefaultProject

# Now all these commands "just work" without repetitive typing
azdocli boards work-item list       # List work items assigned to me
azdocli repos list                  # Uses default project
azdocli pipelines list              # Uses default project
azdocli repos list --project Other  # Override when needed

This simple feature probably saves me dozens of keystrokes every day. It’s those small quality-of-life improvements that make tools truly enjoyable to use.

The Parallel Cloning Challenge

Implementing parallel repository cloning was one of the most rewarding technical challenges. The original approach was straightforward - clone repositories one by one. But watching paint dry would have been more exciting.

The breakthrough came when I realized that most of the time was spent waiting for network operations, not actual CPU work. This was also the perfect chance to learn Rust’s async capabilities:

# The magic command that changed everything
azdocli repos clone --parallel --concurrency 32 --yes

Watching 32 repositories clone simultaneously while seeing real-time progress updates was genuinely exciting. It felt like upgrading from a bicycle to a car.

Daily Workflow

Morning Standup Preparation

Every morning before our team standup, I used to manually check multiple pipelines and pull requests across different projects. It was a tedious ritual involving multiple browser tabs and lots of clicking.

Now my morning routine looks like this:

# See my work items
azdocli boards work-item list

# Check my pull requests
azdocli repos pr list --repo MyMainRepo

# See what work items need attention
azdocli boards work-item show --id 123 --web

Three commands, executed in seconds, and I’m fully prepared for standup. My teammates often ask how I’m always so up-to-date on project status!

The Emergency Response

A critical production issue that required immediate attention. While others were still loading their browsers and navigating through Azure DevOps web interface, I had already:

1. Triggered the hotfix pipeline: azdocli pipelines run --id 42
2. Created an emergency work item: azdocli boards work-item create bug --title "Critical login issue" --description "Users unable to authenticate"
3. Opened the build status directly in my browser for monitoring

The entire response took less than 20 seconds and I never left the context of my editor or terminal

Pull Request Management

# List all pull requests for a repository
azdocli repos pr list --repo MyRepository

# Show details of a specific pull request
azdocli repos pr show --repo MyRepository --id 123

# Create a new pull request
azdocli repos pr create --repo MyRepository --source "feature/my-feature" --target "main" --title "My Feature" --description "Description"

# Create with minimal information - target defaults to 'main'
azdocli repos pr create --repo MyRepository --source "feature/my-feature" --title "My Feature"

Pipeline Management

# List all pipelines
azdocli pipelines list

# Show all runs for a pipeline
azdocli pipelines runs --id 42

# Show details of a specific pipeline build
azdocli pipelines show --id 42 --build-id 123

# Run a pipeline
azdocli pipelines run --id 42

Board Management

# Show "my" work items
azdocli boards work-item list

# Show details of a specific work item
azdocli boards work-item show --id 123

# Open work item directly in web browser
azdocli boards work-item show --id 123 --web

# Create a new work item (supported types: bug, task, user-story, feature, epic)
azdocli boards work-item create bug --title "Fix login issue" --description "Users cannot login after password change"

# Update a work item
azdocli boards work-item update --id 123 --title "New title" --state "Active" --priority 2

# Delete a work item permanently
azdocli boards work-item delete --id 123

# Soft delete a work item by changing state to "Removed"
azdocli boards work-item delete --id 123 --soft-delete

Community and Lessons Learned

The Open Source Journey

Building azdocli has been more than just solving my own problems - it’s been a learning journey about the Rust ecosystem. The Azure DevOps Rust API that I built upon is itself a testament to the power of code generation and the thoughtful design of the Azure DevOps team.

What started as a personal frustration project has now grown into something I genuinely believe can help other developers be more productive. The feedback from early users has been incredibly encouraging, with many sharing their own stories of how the tool has streamlined their workflows.

Performance Numbers That Matter

Here’s what really gets me excited: the difference isn’t just subjective. During development, I did some basic benchmarking:

• Official Azure DevOps CLI: Takes seconds per command
• azdocli: 50-200 milliseconds per command

That’s not just a performance improvement - it’s a fundamentally different user experience. When commands execute faster than you can blink, it changes how you think about automation and scripting.

Advanced Features Born from Real Needs

Parallel Repository Cloning

One of the standout features is the ability to clone multiple repositories in parallel:

• Bulk cloning: Clone all repositories from a project with a single command
• Target directory: Specify where to clone repositories (defaults to current directory)
• Confirmation prompts: Interactive confirmation with repository listing before cloning
• Automation support: Skip prompts with --yes flag for CI/CD scenarios
• Parallel execution: Use --parallel flag to clone multiple repositories simultaneously
• Concurrency control: Adjust the number of concurrent operations with --concurrency (1-8)

Security Best Practices

When working with Personal Access Tokens:

• Never commit your PAT to version control
• Use environment variables or secure storage for automation
• Regularly rotate your tokens
• Use the minimum required permissions
• Store tokens securely and never share them

Error Handling: Learning from Mistakes

The CLI provides comprehensive error handling with:

• Clear feedback when repositories, pipelines, or work items are not found
• Helpful suggestions when authentication fails
• Validation of required parameters before making API calls
• User-friendly formatting with emoji icons for better readability

Every error message in azdocli has a story behind it - usually me running into that exact problem during development and thinking “how can I make this less confusing for the next person?”

Real-World Impact: The Numbers

Since releasing azdocli, I’ve tracked some interesting metrics about my own usage:

• Daily time saved: Approximately 15-20 minutes (mostly from faster command execution and parallel operations)
• Reduced context switching: 60% fewer browser tab switches during development work
• Automation adoption: Increased script usage by 3x due to reliable --yes flags and fast execution

But the real impact isn’t in the numbers - it’s in the reduced friction. When tools get out of your way, you can focus on what really matters: building great software.

Example Use Cases

• Development Workflow: Quickly list and trigger pipelines, create pull requests, and manage work items
• Repository Operations: Clone entire project repositories in parallel, view repository details, and manage pull requests
• CI/CD Automation: Integrate with build scripts using --yes flags to skip confirmations
• Work Item Management: Create, update, and track bugs, tasks, user stories, features, and epics
• Team Collaboration: Open work items and pull requests directly in the browser for quick access

Building from Source

If you prefer to build from source:

# Clone the repository
git clone https://github.com/christianhelle/azdocli.git
cd azdocli

# Build the project
cargo build

# Run tests
cargo test

# Run the CLI
cargo run -- <command>

Testing

The project includes comprehensive integration tests that verify functionality against real Azure DevOps instances. Tests cover repository operations including create, show, clone, and delete operations.

Looking Forward

Building azdocli was a learning exercise. I have built the features that I personally need and use and I don’t have plans for newer features. If you have any ideas and feature requests then feel free to create an issue on the Github repository and I’ll see what I can do. Or even better, implement the feature yourself and I’ll make sure we merge your pull request in and get it released

Back in 2011, I found myself in a predicament that many developers face. I was working extensively with mobile applications that relied heavily on SQLite databases for local data persistence. While there were several database management tools available at the time, most were either too heavyweight for my needs, lacked cross-platform compatibility, or simply didn’t provide the streamlined workflow I required for rapid development and debugging. I needed a tool that could do what none of the existing tools could do.

The mobile development landscape in 2011 was quite different from today. Most of the work I did ran on even older Windows CE based handheld devices. These industrial devices had a 15-year lifetime, and cost a fortune. I was dealing with resource-constrained devices, and every byte mattered. SQLite was (and still is) the go-to solution for local data storage, but debugging and managing these databases during development was often cumbersome. I needed something fast, lightweight, and intuitive – a tool that could keep up with my development workflow without getting in the way. It also needed to work on MacOS, Windows, and Linux

That’s when I decided to create SQLite Query Analyzer. The goal was simple: build a no-nonsense, efficient database management tool that would allow me to quickly inspect, query, and modify SQLite databases during mobile app development. I chose C++ for its performance characteristics and Qt for its excellent cross-platform capabilities and mature UI framework.

The Technical Foundation

From the beginning, SQLite Query Analyzer was designed with several core principles in mind:

Performance First: Working with mobile development taught me to respect the value of speed and efficiency. The application needed to start instantly, load databases instantly, and execute queries without delay.

Cross-Platform Compatibility: Developing for Windows, macOS, and Linux required a tool that could run reliably on all major operating systems. Qt’s robust cross-platform support enabled me to maintain a single codebase while delivering native experiences across different environments.

Simplicity and Usability: The interface needed to be intuitive enough for quick database inspections during debugging sessions, yet powerful enough for more complex database management tasks.

Modern UI Paradigms: Even in 2011, I wanted the application to feel contemporary and integrate well with the native look and feel of each operating system.

Features That Matter

Over the years, SQLite Query Analyzer has evolved to include features that directly address real-world database management needs:

Theme Awareness: In our modern development environments, dark mode isn’t just a preference – it’s often a necessity for long coding sessions. The application automatically detects and adapts to your system’s color theme, providing a comfortable viewing experience in both light and dark modes.

Intelligent Query Interface: The application provides a clean, syntax-highlighted SQL editor that makes writing and executing queries a pleasant experience. Whether you’re running a simple SELECT statement or a complex JOIN operation, the interface stays out of your way and lets you focus on the data.

Speed: Loading a database over 100GB takes microseconds. Executing queries are equally fast (of course given that the query is also fast)

Direct Table Editing: One of the features I’m most proud of is the ability to edit table data directly within the interface. This eliminates the need to write UPDATE statements for simple data modifications, significantly speeding up the development and testing process.

Session Persistence: The application remembers your last session, including open databases, recent queries, and window positioning. This might seem like a small detail, but it makes a huge difference in daily workflow efficiency.

Data Export Capabilities: Need to share your database structure or data? The tool can export schemas as CREATE TABLE statements and data as SQL INSERT scripts or CSV files. This has proven invaluable for documentation, migration scenarios, and sharing sample data with team members.

Modernization

Recently, I decided it was time to give this decade-old project the attention it deserved. The C++ landscape has evolved significantly since 2011, with C++17 and C++20 introducing numerous improvements that make code more expressive, safer, and more maintainable. Similarly, Qt has continued to innovate, with Qt 6 bringing substantial improvements in performance, API design, and cross-platform consistency.

The modernization effort focused on several key areas:

Modern C++ Standards: The codebase has been updated to leverage C++17 and C++20 features, including structured bindings, constexpr enhancements, and improved type deduction. This makes the code more readable and allows the compiler to perform better optimizations.

Qt 6 Migration: Moving to Qt 6 brought numerous benefits, including better high-DPI support, system-aware themes for light and dark mode, improved rendering performance, and more consistent behavior across platforms.

Enhanced Build System: The project now uses CMake with modern practices, making it easier to build across different platforms and integrate with various development environments. The build system now properly handles dependencies and provides clear configuration options for different deployment scenarios.

Improved Code Architecture: Years of experience have taught me better patterns for organizing C++ code. The modernized version features cleaner separation of concerns, better error handling, and more robust memory management practices.

CI/CD Integration: The project now includes comprehensive continuous integration pipelines for Windows, macOS, and Linux, ensuring that changes don’t break compatibility across platforms. This automation gives me confidence when making changes and helps maintain the quality standards the project deserves.

Working with Qt and SQLite

One of the most interesting aspects of this project has been the intersection of Qt’s powerful database abstraction layer with SQLite’s unique characteristics. Qt’s QSqlDatabase and related classes provide an excellent foundation for database operations, but SQLite’s specific features and behavior patterns require careful consideration.

The cross-platform nature of both Qt and SQLite creates some fascinating technical challenges. File path handling, for example, needs to account for different path separators and naming conventions across operating systems. Similarly, font rendering and UI scaling behaviors vary significantly between platforms, requiring careful testing and adjustment to ensure a consistent user experience.

The project has also been a testament to the longevity of well-designed technologies. Both C++ and Qt have proven to be incredibly stable platforms for building desktop applications. Code written in 2011 still compiles and runs today with minimal modifications, which speaks to the maturity and backward compatibility of these technologies.

Perhaps most importantly, this project has reinforced my belief in the value of creating tools that enhance developer productivity. In an industry that’s constantly evolving and introducing new frameworks, platforms, and paradigms, having reliable, efficient tools for fundamental tasks like database management remains as important as ever.

Looking Forward

As we move further into 2025, SQLite Query Analyzer continues to serve its original purpose while adapting to modern development needs. The recent modernization ensures that it will continue to be a valuable tool for developers working with SQLite databases, whether they’re building mobile applications, desktop software, or embedded systems.

The open-source nature of the project means that it can continue to evolve with community input and contributions. I’ve always believed that the best tools are those that grow organically based on real-world usage and feedback from the people who rely on them daily.

For developers interested in C++ desktop application development, the project also serves as a practical example of how to build cross-platform applications using Qt. The source code demonstrates real-world patterns for database integration, UI design, and cross-platform deployment – knowledge that’s valuable regardless of the specific domain you’re working in.

Try It Yourself

SQLite Query Analyzer is available as an open-source project on GitHub, complete with installation and build instructions for Windows, MacOS, and Linux. Whether you’re a mobile developer working with SQLite databases, a desktop application developer looking for a lightweight database tool, or simply someone interested in seeing how modern C++ and Qt can be used together, I encourage you to give it a try.

The project includes comprehensive build documentation and automated builds for all major platforms, making it easy to get started regardless of your development environment. And if you find it useful or have suggestions for improvements, I’d love to hear from you – that’s the beauty of open-source development.

The use of .http files were not immediately adopted by my teams so I started looking at other alternatives, particularly, Scalar. Other teams I work with have built a work flow based on sharing Postman Collections configured with Authentication and multiple environments, like Dev, Test, and Production. Scalar feels a lot like Postman which caught the interest of teams around me

You can try out Scalar here. It looks like this:

In any project I’m involved in, one of the first thing I do, even before setting up a CI/CD pipeline, is to configure security. This usually uses OAuth2 with the implicit (or authorization code) flow and Azure Entra ID as a Secure Token Service (STS) for authentication.

This post will show you how to setup a .NET 9.0 project that produces an OpenAPI docment and will demonstrate how to use Scalar instead of Swagger UI. We will configure Scalar to authenticate against Azure Entra ID.

Let’s start by creating a simple API with .NET 9.0 (AOT)

By default, the .csproj file looks something like this:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <InvariantGlobalization>true</InvariantGlobalization>
    <PublishAot>true</PublishAot>
  </PropertyGroup>
</Project>

And the Program.cs

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.ConfigureHttpJsonOptions(
    options =>
    {
        options.SerializerOptions.TypeInfoResolverChain.Insert(
            0,
            AppJsonSerializerContext.Default);
    })

var app = builder.Build();
var todosApi = app.MapGroup("/todos");

var sampleTodos = new Todo[]
{
    new(1, "Walk the dog"),
    new(2, "Do the dishes", DateOnly.FromDateTime(DateTime.Now)),
    new(3, "Do the laundry", DateOnly.FromDateTime(DateTime.Now.AddDays(1))),
    new(4, "Clean the bathroom"),
    new(5, "Clean the car", DateOnly.FromDateTime(DateTime.Now.AddDays(2)))
};

todosApi.MapGet("/", () => sampleTodos);
todosApi.MapGet(
    "/{id}",
    (int id) =>
        sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
            ? Results.Ok(todo)
            : Results.NotFound());

app.Run();

public record Todo(
    int Id,
    string? Title,
    DateOnly? DueBy = null,
    bool IsComplete = false);

[JsonSerializable(typeof(Todo[]))]
internal partial class AppJsonSerializerContext : JsonSerializerContext
{
}

Next, we need to install a couple of NuGet packages

• Microsoft.AspNetCore.Authentication.JwtBearer - as of writing v9.0.1
• Microsoft.AspNetCore.OpenApi - as of writing v9.0.1
• Scalar.AspNetCore - as of writing v1.2.*

The .csproj file should now look like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <InvariantGlobalization>true</InvariantGlobalization>
    <PublishAot>true</PublishAot>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.1" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.1" />
    <PackageReference Include="Scalar.AspNetCore" Version="1.2.*" />
  </ItemGroup>

</Project>

Next, we need to configure the API to expose OpenAPI specifications using the Microsoft OpenAPI toolset. We need to register the Microsoft OpenAPI dependencies using the AddOpenApi() extension method to IServiceCollection and configure the middleware using the UseOpenApi() on the WebApplication

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.ConfigureHttpJsonOptions(
    options =>
    {
        options.SerializerOptions.TypeInfoResolverChain.Insert(
            0,
            AppJsonSerializerContext.Default);
    })
    .AddOpenApi();

...

var app = builder.Build();
app.UseOpenApi();

...

Next, we configure Scalar. This is done setting up the Scalar middleware calling MapScalarApiReference() on the WebApplication. You will need to import the Scalar.AspNetCore namespace

using Scalar.AspNetCore;

...

var app = builder.Build();
app.UseOpenApi();
app.MapScalarApiReference();

...

With this, we should be able to see the Scalar page on /scalar/v1. It looks something like this:

Clicking on the Test Request button from the GET /todos section will allow you to perform tests against the endpoint. With the current setup, it would look something like this:

By now, we have a fully functional API without any security.

Next, let’s secure the API. For this example we use JWT Bearer tokens containing the audience and role claims. To do this, we use AddAuthentication() and AddAuthorization() on the IServiceCollection and enable middleware using UseAuthentication() and UseAuthorization() on the WebApplication.

We need to configure the API require the JWT Bearer token to have the following claims

• aud - Identifies the intended recipient of the token. In access_tokens and id_tokens, the audience is the App Registration Application URI ID, specified under the Expose an API section of your App Registration, or if not specified it is the App Registration Application ID assigned to your app in the Azure portal. Your app should validate this value, and reject the token if the value does not match.

• iss- Identifies the security token service (STS) that constructs and returns the token, and the Azure Entra ID tenant in which the user was authenticated. If the token was issued by the v2.0 endpoint, the URI will end in /v2.0. The app should use the GUID portion of the claim to restrict the set of tenants that can sign in to the app, if applicable.

• role - The set of permissions exposed by your application that the requesting application has been given permission to call. This is used during the client-credentials flow in place of user scopes, and is only present in applications tokens.

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.ConfigureHttpJsonOptions(
    options =>
    {
        options.SerializerOptions.TypeInfoResolverChain.Insert(
            0,
            AppJsonSerializerContext.Default);
    })
    .AddOpenApi()
    .AddAuthorization()
    .AddAuthentication()
    .AddJwtBearer(o =>
        {
            o.Audience = "api://[app registration client id]";
            o.Authority = "https://login.microsoftonline.com/[tenant id]";
        });

...

var app = builder.Build();
app.UseOpenApi();
app.UseAuthorization();
app.UseAuthentication();
app.MapScalarApiReference();

...

The Audience and Authority will be used in multiple places so it’s best to extract a constants class for this. While we’re at it, let’s add some other constants that will be used later

internal class Constants
{
    public const string Authority = "https://login.microsoftonline.com/[tenant id]";
    public const string ClientId = "[Scalar App Registration Application ID]";
    public const string Audience = "api://[app registration client id]";
    public const string DefaultScope = $"{Audience}/.default";
    public const string Scheme = "Bearer";
}

Now we need to require roles to access our todos endpoints. Let’s keep it simple, and use a single role called todo.read. To setup this up we the RequireAuthorization() extension method and configure it’s options to use RequireRole("todo.read")

...

var todosApi = app.MapGroup("/todos");
todosApi
    .MapGet("/", () => sampleTodos)
    .RequireAuthorization(o => o.RequireRole("todo.read"));

todosApi
    .MapGet("/{id}", (int id) =>
        sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
            ? Results.Ok(todo)
            : Results.NotFound())
    .RequireAuthorization(o => o.RequireRole("todo.read"));

...

Right now, we have no way of retrieving an JWT Bearer token from Scalar itself. But you can always acquire an access token yourself, one way to do this is to use Azure CLI with the following command, assuming that you are logged in to the same tenant and have been granted the todo.read role on the Azure Entra ID Enterprise Application associated to the App Registration.

az account get-access-token --scope [Some Application ID URI]/.default

To enable OAuth2 authentication on Scalar, we need to ensure that the OpenAPI document exposed by the API defines this securitySchemes. To do so, we need to setup a Document Transformer things in AddOpenApi(). A Document Transformer implements the IOpenApiDocumentTransformer interface. If you have previously worked with Swashbuckle.AspNetCore, then this should feel familiar to you.

The following code confgures a security scheme that enables the OAuth2 Implicit grant flow

using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;

public class OpenApiSecuritySchemeTransformer
    : IOpenApiDocumentTransformer
{
    public Task TransformAsync(
        OpenApiDocument document, 
        OpenApiDocumentTransformerContext context,
        CancellationToken cancellationToken)
    {
        var securitySchema =
            new OpenApiSecurityScheme
            {
                Type = SecuritySchemeType.OAuth2,
                Scheme = "Bearer",
                BearerFormat = "JWT",
                Flows = new OpenApiOAuthFlows
                {
                    Implicit = new OpenApiOAuthFlow
                    {
                        AuthorizationUrl = new Uri($"{Constants.Authority}/oauth2/v2.0/authorize"),
                        TokenUrl = new Uri($"{Constants.Authority}/oauth2/v2.0/token"),
                        Scopes = new Dictionary<string, string>
                        {
                            { Constants.DefaultScope, "Access the API" }
                        }
                    }
                }
            };

        var securityRequirement =
            new OpenApiSecurityRequirement
            {
                {
                    new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference
                        {
                            Id = "Bearer",
                            Type = ReferenceType.SecurityScheme,
                        },
                    },
                    []
                }
            };

        document.SecurityRequirements.Add(securityRequirement);
        document.Components = new OpenApiComponents()
        {
            SecuritySchemes = new Dictionary<string, OpenApiSecurityScheme>()
            {
                { "Bearer", securitySchema }
            }
        };

        return Task.CompletedTask;
    }
}

Now that we have a Document Transformer, we need to use it by calling AddDocumentTransformer<OpenApiSecuritySchemeTransformer>() in the OpenApiOptions provided upon AddOpenApi()

var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.ConfigureHttpJsonOptions(
    options =>
    {
        options.SerializerOptions.TypeInfoResolverChain.Insert(
            0,
            AppJsonSerializerContext.Default);
    })
    .AddOpenApi(o => o.AddDocumentTransformer<OpenApiSecuritySchemeTransformer>())
    .AddAuthorization()
    .AddAuthentication()
    .AddJwtBearer(o =>
        {
            o.Audience = "api://[app registration client id]";
            o.Authority = "https://login.microsoftonline.com/[tenant id]";
        });

...

var app = builder.Build();
app.UseOpenApi();
app.UseAuthorization();
app.UseAuthentication();
app.MapScalarApiReference();

...

This should add the securityScheme to the OpenAPI document components when retrieving it from the /openapi/v1.json URL

"components": {
  ...
  "securitySchemes": {
    "Bearer": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://login.microsoftonline.com/[tenant id]/oauth2/v2.0authorize",
          "tokenUrl": "https://login.microsoftonline.com/[tenant id]/oauth2/v2.0/token",
          "scopes": {
            "api://[app registration client id]/.default": "Access the API"
          }
        }
      }
    }
  }
}

When we run the API and browser to the Scalar page then we should now see that the Auth Type dropdown now has a Bearer option

and when selecting Bearer you will see pre-populated options for OAuth2 and a pre-checked scope

Clicking on Authorize should open a window prompting for user credentials

and upon successful authentication, the access token is copied over to Scalar

and is automatically used when sending API requests from Scalar

I published an example project to Github if you want to try it out yourself.