// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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 = "; 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); }