Skip to content

Commit da0baab

Browse files
authored
Merge pull request #345 from argos-ci/greg/cli-analytics-command
feat(cli): add `analytics` command to fetch account analytics
2 parents 51c052e + 450a2df commit da0baab

5 files changed

Lines changed: 447 additions & 7 deletions

File tree

‎packages/api-client/src/schema.ts‎

Lines changed: 140 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,26 @@
44
*/
55

66
export interface paths {
7+
"/accounts/{accountSlug}/analytics": {
8+
parameters: {
9+
query?: never;
10+
header?: never;
11+
path?: never;
12+
cookie?: never;
13+
};
14+
/**
15+
* Get account analytics
16+
* @description Retrieve build and screenshot metrics for an account. The personal access token must be scoped to the account.
17+
*/
18+
get: operations["getAccountAnalytics"];
19+
put?: never;
20+
post?: never;
21+
delete?: never;
22+
options?: never;
23+
head?: never;
24+
patch?: never;
25+
trace?: never;
26+
};
727
"/builds": {
828
parameters: {
929
query?: never;
@@ -696,6 +716,67 @@ export interface components {
696716
* @example 42
697717
*/
698718
BuildNumber: string;
719+
AccountAnalytics: {
720+
screenshots: {
721+
series: {
722+
total: number;
723+
/** @description Counts keyed by project ID. Use the sibling `projects` array to resolve each project name. */
724+
projects: {
725+
[key: string]: number;
726+
};
727+
/** @description Unix timestamp in milliseconds at the start of the period. */
728+
ts: number;
729+
}[];
730+
all: {
731+
total: number;
732+
/** @description Counts keyed by project ID. Use the sibling `projects` array to resolve each project name. */
733+
projects: {
734+
[key: string]: number;
735+
};
736+
};
737+
projects: {
738+
id: string;
739+
name: string;
740+
}[];
741+
};
742+
builds: {
743+
series: {
744+
total: number;
745+
/** @description Counts keyed by project ID. Use the sibling `projects` array to resolve each project name. */
746+
projects: {
747+
[key: string]: number;
748+
};
749+
changesDetected: number;
750+
noChanges: number;
751+
accepted: number;
752+
rejected: number;
753+
/** @description Unix timestamp in milliseconds at the start of the period. */
754+
ts: number;
755+
}[];
756+
all: {
757+
total: number;
758+
/** @description Counts keyed by project ID. Use the sibling `projects` array to resolve each project name. */
759+
projects: {
760+
[key: string]: number;
761+
};
762+
changesDetected: number;
763+
noChanges: number;
764+
accepted: number;
765+
rejected: number;
766+
};
767+
projects: {
768+
id: string;
769+
name: string;
770+
}[];
771+
};
772+
};
773+
/** @description Error response */
774+
Error: {
775+
error: string;
776+
details?: {
777+
message: string;
778+
}[];
779+
};
699780
/** @description Build */
700781
Build: {
701782
id: components["schemas"]["BuildId"];
@@ -771,13 +852,6 @@ export interface components {
771852
/** @description The branch name */
772853
branch: string;
773854
};
774-
/** @description Error response */
775-
Error: {
776-
error: string;
777-
details?: {
778-
message: string;
779-
}[];
780-
};
781855
/** @description A user. */
782856
User: {
783857
id: string;
@@ -1124,6 +1198,65 @@ export interface components {
11241198
}
11251199
export type $defs = Record<string, never>;
11261200
export interface operations {
1201+
getAccountAnalytics: {
1202+
parameters: {
1203+
query: {
1204+
/** @description Start of the analytics period, as an ISO 8601 datetime. */
1205+
from: string;
1206+
/** @description End of the analytics period, as an ISO 8601 datetime. Defaults to the current time. */
1207+
to?: string;
1208+
/** @description Time period used to group each series data point. */
1209+
groupBy: "day" | "week" | "month";
1210+
/** @description Optional project name filter. Pass one value or repeat the parameter for multiple projects. */
1211+
projectNames?: string | string[];
1212+
};
1213+
header?: never;
1214+
path: {
1215+
/** @description Slug of the account to retrieve analytics for. */
1216+
accountSlug: string;
1217+
};
1218+
cookie?: never;
1219+
};
1220+
requestBody?: never;
1221+
responses: {
1222+
/** @description Account analytics */
1223+
200: {
1224+
headers: {
1225+
[name: string]: unknown;
1226+
};
1227+
content: {
1228+
"application/json": components["schemas"]["AccountAnalytics"];
1229+
};
1230+
};
1231+
/** @description Invalid parameters */
1232+
400: {
1233+
headers: {
1234+
[name: string]: unknown;
1235+
};
1236+
content: {
1237+
"application/json": components["schemas"]["Error"];
1238+
};
1239+
};
1240+
/** @description Unauthorized */
1241+
401: {
1242+
headers: {
1243+
[name: string]: unknown;
1244+
};
1245+
content: {
1246+
"application/json": components["schemas"]["Error"];
1247+
};
1248+
};
1249+
/** @description Server error */
1250+
500: {
1251+
headers: {
1252+
[name: string]: unknown;
1253+
};
1254+
content: {
1255+
"application/json": components["schemas"]["Error"];
1256+
};
1257+
};
1258+
};
1259+
};
11271260
createBuild: {
11281261
parameters: {
11291262
query?: never;

‎packages/cli/e2e/analytics.test.ts‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
import { mkdtempSync } from "node:fs";
2+
import { tmpdir } from "node:os";
3+
import { join } from "node:path";
4+
import { beforeAll, describe, expect, test } from "vitest";
5+
6+
import { getRequiredEnv, run, type CommandError } from "./utils";
7+
8+
const userAccessToken = getRequiredEnv("USER_ACCESS_TOKEN");
9+
const projectToken = getRequiredEnv("ARGOS_TOKEN");
10+
const buildNumber = process.env.ARGOS_BUILD_NUMBER || "27748";
11+
12+
const baseEnv: NodeJS.ProcessEnv = {
13+
...process.env,
14+
HOME: mkdtempSync(join(tmpdir(), "argos-cli-e2e-")),
15+
ARGOS_API_BASE_URL: process.env.ARGOS_API_BASE_URL,
16+
ARGOS_TOKEN: "",
17+
};
18+
19+
function expectRunToFail(
20+
args: string[],
21+
overrideEnv?: NodeJS.ProcessEnv,
22+
): CommandError {
23+
try {
24+
run(args, { ...baseEnv, ...overrideEnv });
25+
} catch (error) {
26+
return error as CommandError;
27+
}
28+
throw new Error(
29+
`Expected command to fail: node bin/argos-cli.js ${args.join(" ")}`,
30+
);
31+
}
32+
33+
let account: string;
34+
35+
beforeAll(() => {
36+
// Derive the account slug from the seeded build's URL, so the analytics
37+
// account always matches the account the tokens belong to.
38+
const build = JSON.parse(
39+
run(["build", "get", buildNumber, "--json"], {
40+
...baseEnv,
41+
ARGOS_TOKEN: projectToken,
42+
}).stdout,
43+
);
44+
const match = build.url.match(
45+
/app\.argos-ci\.(?:com|dev(?::\d+)?)\/([^/?#]+)\//,
46+
);
47+
if (!match) {
48+
throw new Error(`Could not parse account from build URL: ${build.url}`);
49+
}
50+
account = match[1];
51+
});
52+
53+
describe("argos analytics", () => {
54+
test("fails when no token is provided", () => {
55+
const error = expectRunToFail(["analytics", "--account", account]);
56+
expect(error.status).not.toBe(0);
57+
expect(error.stderr).toContain("No Argos token found");
58+
});
59+
60+
test("fails when no account is provided", () => {
61+
const error = expectRunToFail(["analytics", "--token", userAccessToken]);
62+
expect(error.status).not.toBe(0);
63+
expect(error.stderr).toContain("An account is required");
64+
});
65+
66+
test("rejects an invalid --group-by value", () => {
67+
const error = expectRunToFail([
68+
"analytics",
69+
"--account",
70+
account,
71+
"--token",
72+
userAccessToken,
73+
"--group-by",
74+
"year",
75+
]);
76+
expect(error.status).not.toBe(0);
77+
expect(error.stderr).toContain("Allowed choices are day, week, month");
78+
});
79+
80+
test("rejects an invalid --from date", () => {
81+
const error = expectRunToFail([
82+
"analytics",
83+
"--account",
84+
account,
85+
"--token",
86+
userAccessToken,
87+
"--from",
88+
"not-a-date",
89+
]);
90+
expect(error.status).not.toBe(0);
91+
expect(error.stderr).toContain('Invalid --from value: "not-a-date"');
92+
});
93+
94+
test("returns account analytics in JSON mode", () => {
95+
const output = run(
96+
["analytics", "--account", account, "--token", userAccessToken, "--json"],
97+
baseEnv,
98+
);
99+
const analytics = JSON.parse(output.stdout);
100+
101+
expect(typeof analytics.screenshots.all.total).toBe("number");
102+
expect(Array.isArray(analytics.screenshots.series)).toBe(true);
103+
expect(Array.isArray(analytics.screenshots.projects)).toBe(true);
104+
105+
expect(typeof analytics.builds.all.total).toBe("number");
106+
expect(typeof analytics.builds.all.changesDetected).toBe("number");
107+
expect(Array.isArray(analytics.builds.series)).toBe(true);
108+
expect(Array.isArray(analytics.builds.projects)).toBe(true);
109+
});
110+
111+
test("prints human-readable analytics", () => {
112+
const output = run(
113+
["analytics", "--account", account, "--token", userAccessToken],
114+
baseEnv,
115+
);
116+
expect(output.stdout).toContain(`Analytics for ${account}`);
117+
expect(output.stdout).toContain("Builds:");
118+
expect(output.stdout).toContain("Screenshots:");
119+
});
120+
121+
test("accepts a bounded date range and --group-by", () => {
122+
// The API caps the range at 365 days, so use a fixed sub-year window.
123+
const output = run(
124+
[
125+
"analytics",
126+
"--account",
127+
account,
128+
"--token",
129+
userAccessToken,
130+
"--from",
131+
"2024-01-01",
132+
"--to",
133+
"2024-06-01",
134+
"--group-by",
135+
"week",
136+
"--json",
137+
],
138+
baseEnv,
139+
);
140+
const analytics = JSON.parse(output.stdout);
141+
expect(typeof analytics.builds.all.total).toBe("number");
142+
});
143+
});

0 commit comments

Comments
 (0)