Something went wrong. Try again.
Zig bindings for all 506 operations of the Forgejo API, generated from its own description, and zfj, a command line built on them.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Tests over the shape of the generated bindings.//!//! Compiling `zfj` at all is the broadest check there is -- 506 operations and//! 246 models either agree with each other or the build fails -- so what is//! left for these is the part a successful compile does not prove: that the//! declarations a caller reaches for are present, named what they were named//! before, and carry the types the specification gives them. Each of these has//! failed silently at some point in getting the generator to this state.
const std = @import("std");const testing = std.testing;
const zfj = @import("zfj");
/// The payload of a `!Owned(T)`-returning operation, i.e. the `T` it parses/// the response body into.fn ResponseModel(comptime operation: anytype) type { const return_type = @typeInfo(@TypeOf(operation)).@"fn".return_type.?; return @typeInfo(return_type).error_union.payload;}
test "the client is constructed from an allocator, an Io and a token" { const init = @typeInfo(@TypeOf(zfj.Client.init)).@"fn"; try testing.expectEqual(@as(usize, 3), init.param_types.len); try testing.expectEqual(std.mem.Allocator, init.param_types[0].?); try testing.expectEqual(std.Io, init.param_types[1].?); try testing.expectEqual([]const u8, init.param_types[2].?); try testing.expectEqual(zfj.Client, init.return_type.?);}
test "operations return the model their response names" { // Forgejo writes almost every successful response as a $ref into the // document's global response table. Left unresolved they all generated as // `!void` and handed the caller nothing. try testing.expectEqual(zfj.Owned(zfj.ServerVersion), ResponseModel(zfj.getVersion)); try testing.expectEqual(zfj.Owned(zfj.Issue), ResponseModel(zfj.issueGetIssue)); try testing.expectEqual(zfj.Owned(zfj.Repository), ResponseModel(zfj.repoGet));}
test "operations returning a list are typed by their element" { // The element type lives in the response schema's `items`; dropping it // leaves `[]const std.json.Value` and the caller parsing the body twice. try testing.expectEqual(zfj.Owned([]const zfj.Issue), ResponseModel(zfj.issueListIssues)); try testing.expectEqual(zfj.Owned([]const zfj.Label), ResponseModel(zfj.issueGetLabels)); try testing.expectEqual(zfj.Owned([]const zfj.Branch), ResponseModel(zfj.repoListBranches));}
test "an operation with an empty response returns nothing" { // `204` against `#/responses/empty` is the one case where `!void` is right. const return_type = @typeInfo(@TypeOf(zfj.issueDelete)).@"fn".return_type.?; try testing.expectEqual(void, @typeInfo(return_type).error_union.payload);}
test "path and query parameters arrive in one params struct" { const options = @typeInfo(zfj.IssueGetIssueParams).@"struct"; try testing.expectEqual(@as(usize, 3), options.field_names.len); try testing.expectEqualStrings("owner", options.field_names[0]); try testing.expectEqual([]const u8, options.field_types[0]); try testing.expectEqualStrings("repo", options.field_names[1]); try testing.expectEqual([]const u8, options.field_types[1]); // `index` is an int64 in the specification, not a string. try testing.expectEqualStrings("index", options.field_names[2]); try testing.expectEqual(i64, options.field_types[2]);}
test "optional query parameters default to null" { // Only the two path parameters are required, so a listing that wants no // filtering says so by leaving the rest out. const options: zfj.IssueListIssuesParams = .{ .owner = "forgejo", .repo = "forgejo" }; try testing.expectEqual(?[]const u8, @FieldType(zfj.IssueListIssuesParams, "state")); try testing.expect(options.state == null); try testing.expect(options.labels == null); // Paging parameters keep the integer type the specification gives them. try testing.expectEqual(?i64, @FieldType(zfj.IssueListIssuesParams, "page")); try testing.expect(options.page == null);}
test "every tag in the specification has a client" { // The ten Swagger tags Forgejo groups its operations under. A tag client // disappearing means its operations moved namespace under the caller. inline for (.{ zfj.ActivitypubClient, zfj.AdminClient, zfj.IssueClient, zfj.MiscellaneousClient, zfj.NotificationClient, zfj.OrganizationClient, zfj.PackageClient, zfj.RepositoryClient, zfj.SettingsClient, zfj.UserClient, }) |Tag| { const init = @typeInfo(@TypeOf(Tag.init)).@"fn"; try testing.expectEqual(*zfj.Client, init.param_types[0].?); try testing.expectEqual(Tag, init.return_type.?); }}
test "a tag client method returns what its flat operation returns" { try testing.expectEqual( ResponseModel(zfj.issueGetIssue), ResponseModel(zfj.IssueClient.issueGetIssue), );}
test "an operation named after a model does not displace it" { // Forgejo declares both an `ActionRun` schema and an `ActionRun` operation. // Lowercasing the operation's first letter is what tells them apart. try testing.expect(@typeInfo(zfj.ActionRun) == .@"struct"); try testing.expectEqual(zfj.Owned(zfj.ActionRun), ResponseModel(zfj.actionRun));}
test "operations Forgejo names in PascalCase are lowercased" { try testing.expectEqual(zfj.Owned(zfj.ListActionRunResponse), ResponseModel(zfj.listActionRuns)); try testing.expect(@typeInfo(zfj.ListActionRunsParams) == .@"struct"); try testing.expect(!@hasDecl(zfj, "ListActionRuns"));}
test "an operation with two tags is on both tag clients" { // `createCurrentUserRepo` is filed under both `repository` and `user`. try testing.expectEqual( ResponseModel(zfj.createCurrentUserRepo), ResponseModel(zfj.RepositoryClient.createCurrentUserRepo), ); try testing.expectEqual( ResponseModel(zfj.createCurrentUserRepo), ResponseModel(zfj.UserClient.createCurrentUserRepo), );}
test "no operation was renamed with an underscore to avoid a collision" { // The generator settles a name collision by appending `_`. zfj never // ships one: a new collision from a Forgejo release fails here, and is // resolved by naming the operation in `operation_name_overrides` in // src/generate.zig. See docs/adr/0001-operation-names-follow-forgejo.md. const suffixed = comptime suffixed: { // Some two thousand declarations, each scanned character by character. @setEvalBranchQuota(200_000); var names: []const []const u8 = &.{}; for (std.meta.declarations(zfj)) |name| { if (std.mem.findScalar(u8, name, '_') != null and @typeInfo(@TypeOf(@field(zfj, name))) == .@"fn") { names = names ++ .{name}; } } break :suffixed names; }; for (suffixed) |name| std.debug.print("suffixed to avoid a collision: {s}\n", .{name}); try testing.expectEqual(@as(usize, 0), suffixed.len);}
test "an operation named by hand keeps its forms" { // `renderMarkdown`'s Raw form is `renderMarkdownRaw`, which is also the // id of the operation next to it, so that one is `renderRawMarkdown`. try testing.expect(@typeInfo(@TypeOf(zfj.renderMarkdownRaw)) == .@"fn"); try testing.expect(@typeInfo(@TypeOf(zfj.renderRawMarkdown)) == .@"fn"); try testing.expect(@typeInfo(@TypeOf(zfj.renderRawMarkdownRaw)) == .@"fn");}
test "a model parses a response body from the API" { const body = \\{ \\ "id": 42, \\ "number": 7, \\ "title": "Something is broken", \\ "state": "open", \\ "user": { "login": "someone", "id": 1 }, \\ "labels": [ { "id": 3, "name": "bug", "color": "ff0000" } ], \\ "created_at": "2026-09-06T00:00:00Z", \\ "an_unknown_field": true \\} ;
const parsed = try std.json.parseFromSlice( zfj.Issue, testing.allocator, body, .{ .ignore_unknown_fields = true }, ); defer parsed.deinit();
const issue = parsed.value; try testing.expectEqual(@as(i64, 42), issue.id.?); try testing.expectEqual(@as(i64, 7), issue.number.?); try testing.expectEqualStrings("Something is broken", issue.title.?); try testing.expectEqualStrings("someone", issue.user.?.login.?); try testing.expectEqual(@as(usize, 1), issue.labels.?.len); try testing.expectEqualStrings("bug", issue.labels.?[0].name.?); // Fields the response leaves out stay null rather than failing the parse. try testing.expect(issue.body == null); try testing.expect(issue.milestone == null);}
test "a response keeps its headers, and finds one by name in any case" { // Forgejo paginates with `Link` and counts with `X-Total-Count`; both are // only headers, so a response that dropped them could not be paged // through. const allocator = testing.allocator; const link = "<https://example.org/api/v1/repos/search?page=2>; rel=\"next\""; const storage = try allocator.dupe(u8, "Link" ++ link ++ "X-Total-Count" ++ "42"); const headers = try allocator.alloc(std.http.Header, 2); const count_at = 4 + link.len; headers[0] = .{ .name = storage[0..4], .value = storage[4..count_at] }; headers[1] = .{ .name = storage[count_at..][0..13], .value = storage[count_at + 13 ..] };
var raw: zfj.RawResponse = .{ .allocator = allocator, .status = .ok, .body = try allocator.dupe(u8, "[]"), .headers = headers, .header_storage = storage, };
try testing.expectEqualStrings(link, raw.header("link").?); try testing.expectEqualStrings("42", raw.header("x-total-count").?); try testing.expect(raw.header("etag") == null);
// Parsing the body carries the headers on into the model's owner. var result = try zfj.parseRawResponse([]const zfj.Repository, raw); defer result.deinit(); try testing.expectEqualStrings("42", result.ok.header("X-Total-Count").?);}
test "array params are slices of their items' type" { // They were `[]const std.json.Value`, and went out on the query string // JSON-encoded: `?status-types="unread"`. try testing.expectEqual(?[]const []const u8, @FieldType(zfj.NotifyGetListParams, "status-types")); try testing.expectEqual(?[]const i64, @FieldType(zfj.RepoListPullRequestsParams, "labels"));}
test "each operation's method, path and params are known at run time" { const info = zfj.operation_info.issueListIssues; try testing.expectEqual(std.http.Method.GET, info.method); try testing.expectEqualStrings("/repos/{owner}/{repo}/issues", info.path); try testing.expectEqualStrings("List a repository's issues", info.summary.?);
const owner = info.param("owner").?; try testing.expectEqual(zfj.OperationInfo.Location.path, owner.location); try testing.expect(owner.required);
const state = info.param("state").?; try testing.expectEqual(@as(usize, 3), state.allowed.len); try testing.expectEqualStrings("closed", state.allowed[0]); try testing.expectEqualStrings("open", state.allowed[1]); try testing.expectEqualStrings("all", state.allowed[2]);
// A request body is a param too, under the argument's name. try testing.expectEqual(zfj.OperationInfo.Location.body, zfj.operation_info.issueCreateIssue.param("requestBody").?.location);}
test "a file to upload is a FormFile, sent as one part of a multipart body" { // The field was there before, as bytes, and was thrown away: the upload // went out with no body at all. try testing.expectEqual(zfj.FormFile, @FieldType(zfj.IssueCreateIssueAttachmentParams, "attachment")); try testing.expectEqual(?zfj.FormFile, @FieldType(zfj.RepoCreateReleaseAttachmentParams, "attachment"));
var multipart: zfj.Multipart = .{}; defer multipart.deinit(testing.allocator); try multipart.add(testing.allocator, "attachment", zfj.FormFile{ .filename = "a \"b\".txt", .bytes = "hello" }); try multipart.add(testing.allocator, "external_url", @as([]const u8, "https://example.org/x")); try multipart.add(testing.allocator, "count", @as(i64, 3)); const form = try multipart.finish(testing.allocator, testing.io); defer form.deinit(testing.allocator);
const prefix = "multipart/form-data; boundary="; try testing.expect(std.mem.startsWith(u8, form.content_type, prefix)); const boundary = form.content_type[prefix.len..]; const expected = try std.fmt.allocPrint(testing.allocator, "--{0s}\r\n" ++ "Content-Disposition: form-data; name=\"attachment\"; filename=\"a %22b%22.txt\"\r\n" ++ "Content-Type: application/octet-stream\r\n\r\nhello\r\n" ++ "--{0s}\r\nContent-Disposition: form-data; name=\"external_url\"\r\n\r\nhttps://example.org/x\r\n" ++ "--{0s}\r\nContent-Disposition: form-data; name=\"count\"\r\n\r\n3\r\n" ++ "--{0s}--\r\n", .{boundary}); defer testing.allocator.free(expected); try testing.expectEqualStrings(expected, form.body);}