@argos-ci/cli 6.4.1 → 6.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,7 +17,7 @@ Interact with and upload screenshots to [argos-ci.com](https://argos-ci.com) fro
17
17
  [![npm dm](https://img.shields.io/npm/dm/@argos-ci/cli.svg)](https://www.npmjs.com/package/@argos-ci/cli)
18
18
  [![npm dt](https://img.shields.io/npm/dt/@argos-ci/cli.svg)](https://www.npmjs.com/package/@argos-ci/cli)
19
19
 
20
- Visit the [Argos CLI documentation](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli) for the full command reference and more.
20
+ Visit the [Argos CLI documentation](https://argos-ci.com/docs/reference/argos-command-line-interface-cli) for the full command reference and more.
21
21
 
22
22
  ## Installation
23
23
 
@@ -41,5 +41,5 @@ npx @argos-ci/cli --help
41
41
 
42
42
  ## Links
43
43
 
44
- - [Official CLI Docs](https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli)
44
+ - [Official CLI Docs](https://argos-ci.com/docs/reference/argos-command-line-interface-cli)
45
45
  - [Discord](https://argos-ci.com/discord)
package/dist/index.mjs CHANGED
@@ -18,6 +18,7 @@ const accountOption = new Option("--account <slug>", "Slug of the account (perso
18
18
  const jsonOption = new Option("--json", "Output machine-readable JSON instead of human-readable text");
19
19
  const projectPathOption = new Option("--project <owner/project>", "Project path in owner/project format. Required for build-number references on review and comment commands");
20
20
  const changeProjectPathOption = new Option("--project <owner/project>", "Project the change belongs to, in owner/project format. Also ARGOS_PROJECT");
21
+ const testProjectPathOption = new Option("--project <owner/project>", "Project the test belongs to, in owner/project format. Also ARGOS_PROJECT. Optional with a project token, which already identifies its project");
21
22
  const METRICS_PERIOD_BY_CHOICE = {
22
23
  "24h": "LAST_24_HOURS",
23
24
  "3d": "LAST_3_DAYS",
@@ -245,6 +246,41 @@ function formatSnapshots(diffs, build) {
245
246
  ...diffs.flatMap((diff) => [...formatSnapshotDiff(diff, build), ""])
246
247
  ].slice(0, -1).join("\n");
247
248
  }
249
+ /** When and where a change was captured, on one line. */
250
+ function formatOccurrence(occurrence) {
251
+ return `${occurrence.date} in build #${occurrence.buildNumber}`;
252
+ }
253
+ function formatTest(test) {
254
+ const lines = [
255
+ `Test ${test.id} [${test.status}]`,
256
+ `Name: ${test.name}`,
257
+ `Build name: ${test.buildName}`,
258
+ `Flakiness: ${formatFlakiness(test.metrics)}`,
259
+ `Builds: ${test.metrics.total}`,
260
+ `Changes: ${test.metrics.changes} (${test.metrics.uniqueChanges} seen only once)`
261
+ ];
262
+ if (test.firstSeenChange) lines.push(`First change: ${formatOccurrence(test.firstSeenChange)}`);
263
+ if (test.lastSeenChange) lines.push(`Last change: ${formatOccurrence(test.lastSeenChange)}`);
264
+ lines.push(`URL: ${test.url}`);
265
+ return lines.join("\n");
266
+ }
267
+ function formatTestChanges(changes) {
268
+ if (changes.length === 0) return "No changes found.";
269
+ return [
270
+ `Changes (${changes.length})`,
271
+ "",
272
+ ...changes.flatMap((change) => [
273
+ `${change.id}${change.ignored ? " [ignored]" : ""}`,
274
+ ` Occurrences: ${change.occurrences}`,
275
+ ` First seen: ${formatOccurrence(change.firstSeen)}`,
276
+ ` Last seen: ${formatOccurrence(change.lastSeen)}`,
277
+ ` Mask: ${formatValue(change.diff.url)}`,
278
+ ` Base file: ${formatValue(change.diff.base?.url)}`,
279
+ ` Head file: ${formatValue(change.diff.head?.url)}`,
280
+ ""
281
+ ])
282
+ ].slice(0, -1).join("\n");
283
+ }
248
284
  function formatChange(change) {
249
285
  return [
250
286
  `Change ${change.id}`,
@@ -686,15 +722,26 @@ async function resolveBuildTarget(reference, options, { auth }) {
686
722
  * Resolve a project-scoped command target: an authenticated client and the
687
723
  * `owner`/`project` pair every project endpoint needs. The project path comes
688
724
  * from `--project owner/project` or the `ARGOS_PROJECT` environment variable.
725
+ *
726
+ * With `auth: "project"` a missing project path falls back to the token's own
727
+ * project, the way {@link resolveBuildTarget} does — that only resolves for a
728
+ * project token, so read-only commands work out of the box in CI. `auth: "user"`
729
+ * requires the path, since a personal access token is not bound to a project.
689
730
  */
690
- async function resolveProjectTarget(options) {
731
+ async function resolveProjectTarget(options, { auth }) {
691
732
  const client = createApiClient(await resolveToken(options));
692
733
  const projectPath = options.project || process.env["ARGOS_PROJECT"];
693
- if (!projectPath) fail("--project <owner/project> is required. Pass it or set ARGOS_PROJECT.");
694
- return {
734
+ if (projectPath) return {
695
735
  client,
696
736
  ...parseProjectPathOrFail(projectPath)
697
737
  };
738
+ if (auth === "user") fail("--project <owner/project> is required. Pass it or set ARGOS_PROJECT.");
739
+ const project = unwrap(await client.GET("/project"));
740
+ return {
741
+ client,
742
+ owner: project.account.slug,
743
+ project: project.name
744
+ };
698
745
  }
699
746
  //#endregion
700
747
  //#region src/lib/run.ts
@@ -747,7 +794,7 @@ function registerBuildGet(build) {
747
794
  }
748
795
  //#endregion
749
796
  //#region src/commands/build/snapshots.ts
750
- const PER_PAGE = 100;
797
+ const PER_PAGE$1 = 100;
751
798
  function isBuildPending(build) {
752
799
  return build.status === "pending" || build.status === "progress";
753
800
  }
@@ -772,7 +819,7 @@ async function fetchAllDiffs(target, options) {
772
819
  },
773
820
  query: {
774
821
  page: String(page),
775
- perPage: String(PER_PAGE),
822
+ perPage: String(PER_PAGE$1),
776
823
  metricsPeriod: options.metricsPeriod,
777
824
  ...options.needsReview ? { needsReview: "true" } : {}
778
825
  }
@@ -1417,7 +1464,7 @@ function defineChangeAction(opts) {
1417
1464
  return (change) => {
1418
1465
  change.command(opts.name).description(opts.description).argument("<changeId>", "Change ID, taken from a diff's `change.id` (see `argos build snapshots`)").addOption(tokenOption).addOption(changeProjectPathOption).addOption(metricsPeriodOption).addOption(jsonOption).action(async (changeId, options) => {
1419
1466
  try {
1420
- const { client, owner, project } = await resolveProjectTarget(options);
1467
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1421
1468
  output(await opts.perform({
1422
1469
  client,
1423
1470
  owner,
@@ -1467,6 +1514,286 @@ function changeCommand(program) {
1467
1514
  registerChangeUnignore(change);
1468
1515
  }
1469
1516
  //#endregion
1517
+ //#region src/commands/test/changes.ts
1518
+ const PER_PAGE = 100;
1519
+ const ignoredOption = new Option("--ignored <boolean>", "Only the changes currently ignored (`true`) or only the ones still under review (`false`)").choices(["true", "false"]);
1520
+ /** Fetch every change of a test, following pagination. */
1521
+ async function fetchAllChanges(target, testId, options) {
1522
+ const { client, owner, project } = target;
1523
+ const results = [];
1524
+ for (let page = 1;; page++) {
1525
+ const data = unwrap(await client.GET("/projects/{owner}/{project}/tests/{testId}/changes", { params: {
1526
+ path: {
1527
+ owner,
1528
+ project,
1529
+ testId
1530
+ },
1531
+ query: {
1532
+ page: String(page),
1533
+ perPage: String(PER_PAGE),
1534
+ metricsPeriod: options.metricsPeriod,
1535
+ ...options.ignored ? { ignored: options.ignored } : {}
1536
+ }
1537
+ } }));
1538
+ results.push(...data.results);
1539
+ if (results.length >= data.pageInfo.total || data.results.length === 0) break;
1540
+ }
1541
+ return results;
1542
+ }
1543
+ function registerTestChanges(test) {
1544
+ test.command("changes").description("List the distinct changes a test produced over a period, most frequent first").argument("<testId>", "Test ID, taken from a diff's `test.id` (see `argos build snapshots`)").addOption(ignoredOption).addOption(tokenOption).addOption(testProjectPathOption).addOption(metricsPeriodOption).addOption(jsonOption).action(async (testId, options) => {
1545
+ try {
1546
+ output(await fetchAllChanges(await resolveProjectTarget(options, { auth: "project" }), testId, {
1547
+ metricsPeriod: toMetricsPeriod(options.metricsPeriod),
1548
+ ignored: options.ignored
1549
+ }), options, formatTestChanges);
1550
+ } catch (error) {
1551
+ handleCliError(error, "project");
1552
+ }
1553
+ });
1554
+ }
1555
+ //#endregion
1556
+ //#region src/commands/test/comment/create.ts
1557
+ function registerTestCommentCreate(comment) {
1558
+ comment.command("create").description("Post a comment (or reply) on a test").argument("<testId>", "Test ID, taken from a diff's `test.id`").option("--body <markdown>", "Markdown body of the comment").option("--body-file <path>", "Read the comment body from a Markdown file").option("--reply-to <threadId>", "Reply to an existing thread (its root comment ID)").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, options) => {
1559
+ try {
1560
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1561
+ const body = await resolveBody(options, { required: true });
1562
+ output(unwrap(await client.POST("/projects/{owner}/{project}/tests/{testId}/comments", {
1563
+ params: { path: {
1564
+ owner,
1565
+ project,
1566
+ testId
1567
+ } },
1568
+ body: {
1569
+ body,
1570
+ threadId: options.replyTo
1571
+ }
1572
+ })), options, formatComment);
1573
+ } catch (error) {
1574
+ handleCliError(error, "user");
1575
+ }
1576
+ });
1577
+ }
1578
+ //#endregion
1579
+ //#region src/commands/test/comment/_action.ts
1580
+ /**
1581
+ * Register a `test comment <name> <testId> <commentId>` command that runs
1582
+ * `perform` and prints the returned comment. Used for the single-comment actions
1583
+ * that share the same shape (get, delete, resolve, subscribe, …), mirroring
1584
+ * `defineCommentAction` on the build side.
1585
+ */
1586
+ function defineTestCommentAction(opts) {
1587
+ return (comment) => {
1588
+ comment.command(opts.name).description(opts.description).argument("<testId>", "Test ID, taken from a diff's `test.id`").argument("<commentId>", "ID of the comment").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, commentId, options) => {
1589
+ try {
1590
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1591
+ output(await opts.perform({
1592
+ client,
1593
+ owner,
1594
+ project,
1595
+ testId,
1596
+ commentId
1597
+ }), options, formatComment);
1598
+ } catch (error) {
1599
+ handleCliError(error, "user");
1600
+ }
1601
+ });
1602
+ };
1603
+ }
1604
+ //#endregion
1605
+ //#region src/commands/test/comment/delete.ts
1606
+ const registerTestCommentDelete = defineTestCommentAction({
1607
+ name: "delete",
1608
+ description: "Delete a comment on a test (author or project admin)",
1609
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.DELETE("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}", { params: { path: {
1610
+ owner,
1611
+ project,
1612
+ testId,
1613
+ commentId
1614
+ } } }))
1615
+ });
1616
+ //#endregion
1617
+ //#region src/commands/test/comment/edit.ts
1618
+ function registerTestCommentEdit(comment) {
1619
+ comment.command("edit").description("Update the body of a comment on a test (author only)").argument("<testId>", "Test ID, taken from a diff's `test.id`").argument("<commentId>", "ID of the comment").option("--body <markdown>", "New Markdown body of the comment").option("--body-file <path>", "Read the new body from a Markdown file").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, commentId, options) => {
1620
+ try {
1621
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1622
+ const body = await resolveBody(options, { required: true });
1623
+ output(unwrap(await client.PATCH("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}", {
1624
+ params: { path: {
1625
+ owner,
1626
+ project,
1627
+ testId,
1628
+ commentId
1629
+ } },
1630
+ body: { body }
1631
+ })), options, formatComment);
1632
+ } catch (error) {
1633
+ handleCliError(error, "user");
1634
+ }
1635
+ });
1636
+ }
1637
+ //#endregion
1638
+ //#region src/commands/test/comment/get.ts
1639
+ const registerTestCommentGet = defineTestCommentAction({
1640
+ name: "get",
1641
+ description: "Fetch a single comment on a test",
1642
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.GET("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}", { params: { path: {
1643
+ owner,
1644
+ project,
1645
+ testId,
1646
+ commentId
1647
+ } } }))
1648
+ });
1649
+ //#endregion
1650
+ //#region src/commands/test/comment/list.ts
1651
+ function registerTestCommentList(comment) {
1652
+ comment.command("list").description("List the comments on a test").argument("<testId>", "Test ID, taken from a diff's `test.id`").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, options) => {
1653
+ try {
1654
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1655
+ output(unwrap(await client.GET("/projects/{owner}/{project}/tests/{testId}/comments", { params: { path: {
1656
+ owner,
1657
+ project,
1658
+ testId
1659
+ } } })), options, formatComments);
1660
+ } catch (error) {
1661
+ handleCliError(error, "user");
1662
+ }
1663
+ });
1664
+ }
1665
+ //#endregion
1666
+ //#region src/commands/test/comment/react.ts
1667
+ function registerTestCommentReact(comment) {
1668
+ comment.command("react").description("Add an emoji reaction to a comment on a test").argument("<testId>", "Test ID, taken from a diff's `test.id`").argument("<commentId>", "ID of the comment").argument("<emoji>", "Emoji to react with").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, commentId, emoji, options) => {
1669
+ try {
1670
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1671
+ output(unwrap(await client.POST("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/reactions", {
1672
+ params: { path: {
1673
+ owner,
1674
+ project,
1675
+ testId,
1676
+ commentId
1677
+ } },
1678
+ body: { emoji }
1679
+ })), options, formatComment);
1680
+ } catch (error) {
1681
+ handleCliError(error, "user");
1682
+ }
1683
+ });
1684
+ }
1685
+ //#endregion
1686
+ //#region src/commands/test/comment/resolve.ts
1687
+ const registerTestCommentResolve = defineTestCommentAction({
1688
+ name: "resolve",
1689
+ description: "Mark a comment thread on a test as resolved",
1690
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.POST("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/resolve", { params: { path: {
1691
+ owner,
1692
+ project,
1693
+ testId,
1694
+ commentId
1695
+ } } }))
1696
+ });
1697
+ //#endregion
1698
+ //#region src/commands/test/comment/subscribe.ts
1699
+ const registerTestCommentSubscribe = defineTestCommentAction({
1700
+ name: "subscribe",
1701
+ description: "Follow a comment thread on a test to get notified of replies",
1702
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.POST("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/subscription", { params: { path: {
1703
+ owner,
1704
+ project,
1705
+ testId,
1706
+ commentId
1707
+ } } }))
1708
+ });
1709
+ //#endregion
1710
+ //#region src/commands/test/comment/unreact.ts
1711
+ function registerTestCommentUnreact(comment) {
1712
+ comment.command("unreact").description("Remove your emoji reaction from a comment on a test").argument("<testId>", "Test ID, taken from a diff's `test.id`").argument("<commentId>", "ID of the comment").argument("<emoji>", "Emoji to react with").addOption(tokenOption).addOption(testProjectPathOption).addOption(jsonOption).action(async (testId, commentId, emoji, options) => {
1713
+ try {
1714
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "user" });
1715
+ output(unwrap(await client.DELETE("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/reactions", { params: {
1716
+ path: {
1717
+ owner,
1718
+ project,
1719
+ testId,
1720
+ commentId
1721
+ },
1722
+ query: { emoji }
1723
+ } })), options, formatComment);
1724
+ } catch (error) {
1725
+ handleCliError(error, "user");
1726
+ }
1727
+ });
1728
+ }
1729
+ //#endregion
1730
+ //#region src/commands/test/comment/unresolve.ts
1731
+ const registerTestCommentUnresolve = defineTestCommentAction({
1732
+ name: "unresolve",
1733
+ description: "Reopen a resolved comment thread on a test",
1734
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.POST("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/unresolve", { params: { path: {
1735
+ owner,
1736
+ project,
1737
+ testId,
1738
+ commentId
1739
+ } } }))
1740
+ });
1741
+ //#endregion
1742
+ //#region src/commands/test/comment/unsubscribe.ts
1743
+ const registerTestCommentUnsubscribe = defineTestCommentAction({
1744
+ name: "unsubscribe",
1745
+ description: "Stop following a comment thread on a test",
1746
+ perform: async ({ client, owner, project, testId, commentId }) => unwrap(await client.DELETE("/projects/{owner}/{project}/tests/{testId}/comments/{commentId}/subscription", { params: { path: {
1747
+ owner,
1748
+ project,
1749
+ testId,
1750
+ commentId
1751
+ } } }))
1752
+ });
1753
+ //#endregion
1754
+ //#region src/commands/test/comment/index.ts
1755
+ function registerTestComment(test) {
1756
+ const comment = test.command("comment").description("List, post, and act on comments left on a test");
1757
+ registerTestCommentList(comment);
1758
+ registerTestCommentCreate(comment);
1759
+ registerTestCommentGet(comment);
1760
+ registerTestCommentEdit(comment);
1761
+ registerTestCommentDelete(comment);
1762
+ registerTestCommentResolve(comment);
1763
+ registerTestCommentUnresolve(comment);
1764
+ registerTestCommentReact(comment);
1765
+ registerTestCommentUnreact(comment);
1766
+ registerTestCommentSubscribe(comment);
1767
+ registerTestCommentUnsubscribe(comment);
1768
+ }
1769
+ //#endregion
1770
+ //#region src/commands/test/get.ts
1771
+ function registerTestGet(test) {
1772
+ test.command("get").description("Fetch a test and its flakiness metrics").argument("<testId>", "Test ID, taken from a diff's `test.id` (see `argos build snapshots`)").addOption(tokenOption).addOption(testProjectPathOption).addOption(metricsPeriodOption).addOption(jsonOption).action(async (testId, options) => {
1773
+ try {
1774
+ const { client, owner, project } = await resolveProjectTarget(options, { auth: "project" });
1775
+ output(unwrap(await client.GET("/projects/{owner}/{project}/tests/{testId}", { params: {
1776
+ path: {
1777
+ owner,
1778
+ project,
1779
+ testId
1780
+ },
1781
+ query: { metricsPeriod: toMetricsPeriod(options.metricsPeriod) }
1782
+ } })), options, formatTest);
1783
+ } catch (error) {
1784
+ handleCliError(error, "project");
1785
+ }
1786
+ });
1787
+ }
1788
+ //#endregion
1789
+ //#region src/commands/test/index.ts
1790
+ function testCommand(program) {
1791
+ const test = program.command("test").description("Inspect a test's flakiness and the changes that keep coming back");
1792
+ registerTestGet(test);
1793
+ registerTestChanges(test);
1794
+ registerTestComment(test);
1795
+ }
1796
+ //#endregion
1470
1797
  //#region src/index.ts
1471
1798
  const rawPkg = await readFile(resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json"), "utf8");
1472
1799
  const pkg = JSON.parse(rawPkg);
@@ -1484,6 +1811,7 @@ whoamiCommand(program);
1484
1811
  createProjectCommand(program);
1485
1812
  analyticsCommand(program);
1486
1813
  changeCommand(program);
1814
+ testCommand(program);
1487
1815
  if (!process.argv.slice(2).length) program.outputHelp();
1488
1816
  else program.parse(process.argv);
1489
1817
  //#endregion
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@argos-ci/cli",
3
3
  "description": "Command-line (CLI) for visual testing with Argos.",
4
- "version": "6.4.1",
4
+ "version": "6.6.0",
5
5
  "bin": {
6
6
  "argos": "./bin/argos-cli.js"
7
7
  },
@@ -14,7 +14,7 @@
14
14
  "url": "https://github.com/argos-ci/argos-javascript.git",
15
15
  "directory": "packages/core"
16
16
  },
17
- "homepage": "https://argos-ci.com/docs/sdks-reference/argos-command-line-interface-cli",
17
+ "homepage": "https://argos-ci.com/docs/reference/argos-command-line-interface-cli",
18
18
  "bugs": {
19
19
  "url": "https://github.com/argos-ci/argos-javascript/issues"
20
20
  },
@@ -34,8 +34,8 @@
34
34
  "access": "public"
35
35
  },
36
36
  "dependencies": {
37
- "@argos-ci/api-client": "0.26.0",
38
- "@argos-ci/core": "6.6.2",
37
+ "@argos-ci/api-client": "0.28.0",
38
+ "@argos-ci/core": "6.7.1",
39
39
  "commander": "^15.0.0",
40
40
  "open": "^11.0.0",
41
41
  "ora": "^9.4.0",
@@ -54,5 +54,5 @@
54
54
  "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
55
55
  "lint": "eslint ."
56
56
  },
57
- "gitHead": "a86f2dc1a243591e064a2d5c4e03d712c8f03b86"
57
+ "gitHead": "3fd83ec12c4e291e813c91cd1e2d4737d014a1d0"
58
58
  }