flakiness 0.277.0 → 0.279.0

package/lib/cli/cli.js

@@ -1034,7 +1034,7 @@ import path7 from "path";
 // ../package.json
 var package_default = {
   name: "@flakiness/monorepo",
-  version: "0.277.0",
+  version: "0.279.0",
   type: "module",
   private: true,
   scripts: {
@@ -2076,6 +2076,8 @@ async function cmdListTests(options) {
       direction: options.sortDir
     },
     fql: options.fql,
+    // Absent => the server falls back to the project's default history type.
+    historyConfig: options.history ? { type: options.history } : void 0,
     timelineSplit: buildTimelineSplit(options)
   }).then((response) => response.page);
   let scope = "default branch";
@@ -2102,7 +2104,8 @@ async function cmdListTests(options) {
     const status = outcomeToStatus(testStats.outcome);
     const duration = humanReadableMs(testStats.durationMs);
     const trend = formatDurationTrend(testStats.durationChangeMs, testStats.durationMs);
-    const flipRate = formatFlipRate(testStats.flipRate);
+    const flipRate = formatRate(testStats.flipRate);
+    const failRate = formatRate(testStats.failRate);
     const env = formatEnv(testStats.env);
     const metadata = formatEnvMetadata(testStats.env);
     lines.push(`### ${index + 1}. ${fullName}`);
@@ -2113,6 +2116,7 @@ async function cmdListTests(options) {
     lines.push(`- Status: ${asInlineCode(status)}`);
     lines.push(`- Duration: ${asInlineCode(duration)} (${asInlineCode(trend)})`);
     lines.push(`- Flip Rate: ${asInlineCode(flipRate)}`);
+    lines.push(`- Fail Rate: ${asInlineCode(failRate)}`);
     lines.push(`- Error: ${error ? asInlineCode(error) : "None"}`);
     lines.push("");
   }
@@ -2166,10 +2170,10 @@ function formatDurationTrend(changeMs, currentMs) {
   const sign = changeMs >= 0 ? "+" : "-";
   return `${sign}${humanReadableMs(Math.abs(changeMs))} (${scale})`;
 }
-function formatFlipRate(flipRate) {
-  if (flipRate === void 0 || !Number.isFinite(flipRate))
+function formatRate(rate) {
+  if (rate === void 0 || !Number.isFinite(rate))
     return "n/a";
-  return `${(flipRate * 100).toFixed(2)}%`;
+  return `${(rate * 100).toFixed(2)}%`;
 }
 function asInlineCode(text) {
   const normalized = text.replace(/\s+/g, " ").trim();
@@ -2192,7 +2196,7 @@ var BUNDLED_SKILLS = [
     "files": [
       {
         "path": "SKILL.md",
-        "content": "---\nname: flakiness-investigation\ndescription: >-\n  TRIGGER when: CI fails, tests fail, PR checks fail, user asks about test results, regressions, flakiness, or test health.\n  Always use this INSTEAD OF `gh` CLI for investigating test failures \u2014 it distinguishes regressions (caused by the PR) from pre-existing failures and flakes.\n  DO NOT TRIGGER when: the user is asking about non-test CI issues (e.g. build failures, deployment problems).\n---\n\n# Flakiness Investigation\n\nUse the `flakiness` CLI to query and analyze test data from Flakiness.io.\n\n## Prerequisites\n\n- The `flakiness` CLI must be available in PATH (installed via `npm install -g flakiness` or `npx flakiness`).\n- A project must be specified: `--project <org/project>` or set `FLAKINESS_PROJECT` env var.\n- Authentication: run `flakiness auth login` first, or set `FLAKINESS_ACCESS_TOKEN`.\n\n## Core command\n\n```bash\nflakiness list tests --project <org/project> [--pr <number>] [--branch <name>] [--fql <query>] [--sort <axis>] [--sort-dir asc|desc] [--page <n>] [--page-size <n>] [--env-name <value>] [--env-path <value>] [--env-category <value>] [--env-os <value>] [--env-arch <value>] [--env-metadata <key=value>]\n```\n\n### Scope options\n\n| Flag | Effect |\n|------|--------|\n| *(none)* | Default branch \u2014 tests from the day of its head commit (in the project's timezone) |\n| `--pr <number>` | Pull request \u2014 tests from the merge-commit of the PR branch into the target branch |\n| `--branch <name>` | Named branch \u2014 tests from the day of its head commit (in the project's timezone) |\n\n`--pr` and `--branch` are mutually exclusive.\n\n### Environment filter options\n\nFilter results by environment. All flags are repeatable. Multiple values for the same flag are OR'd; different flags are AND'd.\n\n| Flag | Filters by | Example |\n|------|-----------|---------|\n| `--env-name <value>` | Environment name | `--env-name chromium` |\n| `--env-path <value>` | Config file path | `--env-path playwright.config.ts` |\n| `--env-category <value>` | Test category | `--env-category playwright` |\n| `--env-os <value>` | OS name + version | `--env-os \"Ubuntu 22.04\"` |\n| `--env-arch <value>` | CPU architecture | `--env-arch x86_64` |\n| `--env-metadata <key=value>` | User-supplied metadata | `--env-metadata browser=chromium` |\n\nThe output for each test shows environment info in the same `key=value` format:\n- **Env** line: system-collected data with keys matching the `--env-*` flag suffixes (`category=`, `name=`, `path=`, `os=`, `arch=`)\n- **Env Metadata** line (if any): user-supplied key=value pairs\n\nThis makes it easy to copy a value from the output and use it as a filter flag.\n\n### Status semantics with `--pr`\n\nWhen querying a PR, the status values have specific meaning:\n\n| Status | Meaning |\n|--------|---------|\n| `regressed` | Test was passing on the target branch but fails in this PR \u2014 **caused by the PR** |\n| `failed` | Test also fails on the target branch \u2014 **pre-existing failure, not caused by the PR** |\n| `flaked` | Test failed but passed on retry \u2014 flaky, not a real failure |\n| `passed` | Test passes |\n| `skipped` | Test was skipped |\n\n### Sort axes\n\n- `outcome` \u2014 sort by test outcome severity (default)\n- `flip_rate` \u2014 sort by flip rate (how often a test flips between pass/fail)\n- `fail_rate` \u2014 sort by fail rate (share of commits where the test's terminal status was failing)\n- `duration` \u2014 sort by test duration\n- `duration_trend` \u2014 sort by duration trend\n- `name` \u2014 sort alphabetically\n\n### Common queries\n\n| Goal | FQL + flags |\n|------|-------------|\n| Flaky tests | `--fql 'flip>0%' --sort flip_rate --sort-dir desc` |\n| Very flaky (>50%) | `--fql 'flip>50%' --sort flip_rate --sort-dir desc` |\n| Tests that have failed (terminal failure) | `--fql 'fail>0%' --sort fail_rate --sort-dir desc` |\n| Tests that fail most often (>50%) | `--fql 'fail>50%' --sort fail_rate --sort-dir desc` |\n| Failed tests | `--fql 's:failed' --sort outcome --sort-dir desc` |\n| Regressions | `--fql 's:regressed'` |\n| All broken tests | `--fql 'status:(failed, regressed)'` |\n| Slow tests | `--fql 'd>5s' --sort duration --sort-dir desc` |\n| Tests matching error | `--fql '$timeout'` |\n| Tests in file | `--fql 'f:login.spec.ts'` |\n| Tests on Linux | `--env-os \"Ubuntu 22.04\"` |\n| Tests for chromium project | `--env-name chromium` |\n| Tests with specific metadata | `--env-metadata browser=firefox` |\n| Linux or macOS failures | `--env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\" --fql 's:failed'` |\n\n## FQL (Filter Query Language)\n\nFull reference: [references/fql.md](references/fql.md)\n\nKey rules:\n- Multiple tokens combine with AND: `s:failed f:e2e` means \"failed AND in e2e files\"\n- Prefix with `-` to exclude: `-#smoke` excludes smoke-tagged tests\n- Same filter type uses OR: `status:(failed, regressed)` means \"failed OR regressed\"\n- Quote values with spaces: `f:'tests/e2e checkout'`\n\n### Filter types\n\n| Filter | Syntax | Example |\n|--------|--------|---------|\n| Text search | `<text>` | `login` |\n| Status | `s:<status>` | `s:failed`, `status:(failed, regressed)` |\n| File | `f:<path>` | `f:login.spec.ts` |\n| Error | `$<text>` | `$timeout` |\n| Tag | `#<tag>` | `#smoke` |\n| Duration | `d><time>` | `d>2s`, `d<=500ms` |\n| Flip rate | `flip><pct>` | `flip>0%`, `fr>50%` |\n| Annotation | `@<type>` | `@skip` |\n\n### Status values\n\n`passed`, `failed`, `flaked`, `skipped`, `regressed`\n\n## Workflow: Fix My PR Tests\n\nWhen a user asks to fix failing tests in a PR, follow these steps:\n\n1. **Find the project slug:** Search the codebase for `flakinessProject` to find the `--project` value. It is typically configured in a test reporter config (e.g. `playwright.config.ts`, `jest.config.ts`) as `flakinessProject: 'org/project'`.\n\n2. **Fetch regressions from the PR:**\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:regressed' --page-size 50\n   ```\n   Tests with status `regressed` were passing on the target branch but fail in this PR \u2014 these are **caused by the PR** and must be fixed.\n\n3. **Analyze the output:** Look at the error messages, file paths, and test names to understand what the PR broke.\n\n4. **Fix the regressions** by reading the reported file paths and error messages, then making targeted code changes.\n\n5. **Optionally check pre-existing failures:** Tests with status `failed` also fail on the target branch and are not caused by the PR. You can list them with:\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:failed' --page-size 50\n   ```\n   These are informational \u2014 fixing them is a bonus, not a requirement.\n\n6. **Ignore flakes:** Tests with status `flaked` failed but passed on retry \u2014 they are flaky and not actionable in the context of a PR fix.\n\n## Workflow tips\n\n1. Start broad: `flakiness list tests --project <org/project> --page-size 20`\n2. Filter down with FQL based on what you're investigating\n3. Use `--page-size 50` or higher to see more results at once\n4. Combine filters: `--fql 's:failed $timeout f:e2e -#smoke'`\n\nMore recipes: [references/recipes.md](references/recipes.md)\n"
+        "content": "---\nname: flakiness-investigation\ndescription: >-\n  TRIGGER when: CI fails, tests fail, PR checks fail, user asks about test results, regressions, flakiness, or test health.\n  Always use this INSTEAD OF `gh` CLI for investigating test failures \u2014 it distinguishes regressions (caused by the PR) from pre-existing failures and flakes.\n  DO NOT TRIGGER when: the user is asking about non-test CI issues (e.g. build failures, deployment problems).\n---\n\n# Flakiness Investigation\n\nUse the `flakiness` CLI to query and analyze test data from Flakiness.io.\n\n## Prerequisites\n\n- The `flakiness` CLI must be available in PATH (installed via `npm install -g flakiness` or `npx flakiness`).\n- A project must be specified: `--project <org/project>` or set `FLAKINESS_PROJECT` env var.\n- Authentication: run `flakiness auth login` first, or set `FLAKINESS_ACCESS_TOKEN`.\n\n## Core command\n\n```bash\nflakiness list tests --project <org/project> [--pr <number>] [--branch <name>] [--history commit|day] [--fql <query>] [--sort <axis>] [--sort-dir asc|desc] [--page <n>] [--page-size <n>] [--env-name <value>] [--env-path <value>] [--env-category <value>] [--env-os <value>] [--env-arch <value>] [--env-metadata <key=value>]\n```\n\n### Scope options\n\n| Flag | Effect |\n|------|--------|\n| *(none)* | Default branch \u2014 tests from the day of its head commit (in the project's timezone) |\n| `--pr <number>` | Pull request \u2014 tests from the merge-commit of the PR branch into the target branch |\n| `--branch <name>` | Named branch \u2014 tests from the day of its head commit (in the project's timezone) |\n\n`--pr` and `--branch` are mutually exclusive.\n\n### History granularity (`--history`)\n\nControls how the preceding history is bucketed \u2014 which affects the duration trend, flip rate, fail rate, and the per-test history. Omit it to use the project's configured default.\n\n| Value | Buckets history by | Use when |\n|-------|--------------------|----------|\n| `--history commit` | Each commit | Pinpointing the exact commit that changed a test's behavior or duration. |\n| `--history day` | Each day (project timezone) | Reviewing a test's **performance over time** \u2014 day-over-day duration trends and flip/fail rates are smoother and less noisy than commit-to-commit, so slow drifts and recurring flakes stand out. |\n\nFor \"is this test getting slower / flakier over time?\" questions, prefer `--history day`:\n\n```bash\nflakiness list tests --project <org/project> --history day --sort duration_trend --sort-dir desc\nflakiness list tests --project <org/project> --history day --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n### Environment filter options\n\nFilter results by environment. All flags are repeatable. Multiple values for the same flag are OR'd; different flags are AND'd.\n\n| Flag | Filters by | Example |\n|------|-----------|---------|\n| `--env-name <value>` | Environment name | `--env-name chromium` |\n| `--env-path <value>` | Config file path | `--env-path playwright.config.ts` |\n| `--env-category <value>` | Test category | `--env-category playwright` |\n| `--env-os <value>` | OS name + version | `--env-os \"Ubuntu 22.04\"` |\n| `--env-arch <value>` | CPU architecture | `--env-arch x86_64` |\n| `--env-metadata <key=value>` | User-supplied metadata | `--env-metadata browser=chromium` |\n\nThe output for each test shows environment info in the same `key=value` format:\n- **Env** line: system-collected data with keys matching the `--env-*` flag suffixes (`category=`, `name=`, `path=`, `os=`, `arch=`)\n- **Env Metadata** line (if any): user-supplied key=value pairs\n\nThis makes it easy to copy a value from the output and use it as a filter flag.\n\n### Status semantics with `--pr`\n\nWhen querying a PR, the status values have specific meaning:\n\n| Status | Meaning |\n|--------|---------|\n| `regressed` | Test was passing on the target branch but fails in this PR \u2014 **caused by the PR** |\n| `failed` | Test also fails on the target branch \u2014 **pre-existing failure, not caused by the PR** |\n| `flaked` | Test failed but passed on retry \u2014 flaky, not a real failure |\n| `passed` | Test passes |\n| `skipped` | Test was skipped |\n\n### Sort axes\n\n- `outcome` \u2014 sort by test outcome severity (default)\n- `flip_rate` \u2014 sort by flip rate (how often a test flips between pass/fail)\n- `fail_rate` \u2014 sort by fail rate (share of commits where the test's terminal status was failing)\n- `duration` \u2014 sort by test duration\n- `duration_trend` \u2014 sort by duration trend\n- `name` \u2014 sort alphabetically\n\n### Common queries\n\n| Goal | FQL + flags |\n|------|-------------|\n| Flaky tests | `--fql 'flip>0%' --sort flip_rate --sort-dir desc` |\n| Very flaky (>50%) | `--fql 'flip>50%' --sort flip_rate --sort-dir desc` |\n| Tests that have failed (terminal failure) | `--fql 'fail>0%' --sort fail_rate --sort-dir desc` |\n| Tests that fail most often (>50%) | `--fql 'fail>50%' --sort fail_rate --sort-dir desc` |\n| Failed tests | `--fql 's:failed' --sort outcome --sort-dir desc` |\n| Regressions | `--fql 's:regressed'` |\n| All broken tests | `--fql 'status:(failed, regressed)'` |\n| Slow tests | `--fql 'd>5s' --sort duration --sort-dir desc` |\n| Tests matching error | `--fql '$timeout'` |\n| Tests in file | `--fql 'f:login.spec.ts'` |\n| Tests on Linux | `--env-os \"Ubuntu 22.04\"` |\n| Tests for chromium project | `--env-name chromium` |\n| Tests with specific metadata | `--env-metadata browser=firefox` |\n| Linux or macOS failures | `--env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\" --fql 's:failed'` |\n\n## FQL (Filter Query Language)\n\nFull reference: [references/fql.md](references/fql.md)\n\nKey rules:\n- Multiple tokens combine with AND: `s:failed f:e2e` means \"failed AND in e2e files\"\n- Prefix with `-` to exclude: `-#smoke` excludes smoke-tagged tests\n- Same filter type uses OR: `status:(failed, regressed)` means \"failed OR regressed\"\n- Quote values with spaces: `f:'tests/e2e checkout'`\n\n### Filter types\n\n| Filter | Syntax | Example |\n|--------|--------|---------|\n| Text search | `<text>` | `login` |\n| Status | `s:<status>` | `s:failed`, `status:(failed, regressed)` |\n| File | `f:<path>` | `f:login.spec.ts` |\n| Error | `$<text>` | `$timeout` |\n| Tag | `#<tag>` | `#smoke` |\n| Duration | `d><time>` | `d>2s`, `d<=500ms` |\n| Flip rate | `flip><pct>` | `flip>0%`, `fr>50%` |\n| Annotation | `@<type>` | `@skip` |\n\n### Status values\n\n`passed`, `failed`, `flaked`, `skipped`, `regressed`\n\n## Workflow: Fix My PR Tests\n\nWhen a user asks to fix failing tests in a PR, follow these steps:\n\n1. **Find the project slug:** Search the codebase for `flakinessProject` to find the `--project` value. It is typically configured in a test reporter config (e.g. `playwright.config.ts`, `jest.config.ts`) as `flakinessProject: 'org/project'`.\n\n2. **Fetch regressions from the PR:**\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:regressed' --page-size 50\n   ```\n   Tests with status `regressed` were passing on the target branch but fail in this PR \u2014 these are **caused by the PR** and must be fixed.\n\n3. **Analyze the output:** Look at the error messages, file paths, and test names to understand what the PR broke.\n\n4. **Fix the regressions** by reading the reported file paths and error messages, then making targeted code changes.\n\n5. **Optionally check pre-existing failures:** Tests with status `failed` also fail on the target branch and are not caused by the PR. You can list them with:\n   ```bash\n   flakiness list tests --project <org/project> --pr <number> --fql 's:failed' --page-size 50\n   ```\n   These are informational \u2014 fixing them is a bonus, not a requirement.\n\n6. **Ignore flakes:** Tests with status `flaked` failed but passed on retry \u2014 they are flaky and not actionable in the context of a PR fix.\n\n## Workflow tips\n\n1. Start broad: `flakiness list tests --project <org/project> --page-size 20`\n2. Filter down with FQL based on what you're investigating\n3. Use `--page-size 50` or higher to see more results at once\n4. Combine filters: `--fql 's:failed $timeout f:e2e -#smoke'`\n\nMore recipes: [references/recipes.md](references/recipes.md)\n"
       },
       {
         "path": "references/fql.md",
@@ -2200,7 +2204,7 @@ var BUNDLED_SKILLS = [
       },
       {
         "path": "references/recipes.md",
-        "content": "# Investigation Recipes\n\nReplace `myorg/myproject` with the target project slug, or set `FLAKINESS_PROJECT`.\n\n## Query a pull request\n\nShows tests from the merge-commit of the PR branch into the target branch.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42\n```\n\n## Find PR regressions (caused by the PR)\n\nTests marked `regressed` were passing on the target branch but fail in this PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:regressed'\n```\n\n## Find pre-existing failures in a PR\n\nTests marked `failed` also fail on the target branch \u2014 not caused by the PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:failed'\n```\n\n## Find all broken tests in a PR\n\nIncludes both PR-caused regressions and pre-existing failures.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 'status:(failed, regressed)' --page-size 50\n```\n\n## Query a specific branch\n\nShows tests from the day of the branch's head commit, in the project's timezone.\n\n```bash\nflakiness list tests --project myorg/myproject --branch feature/login\n```\n\n## Find all flaky tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n## Find the most flaky tests (>50% flip rate)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>50%' --sort flip_rate --sort-dir desc\n```\n\n## Find tests that have ever failed (terminal failure, retries exhausted)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'fail>0%' --sort fail_rate --sort-dir desc\n```\n\n## Find tests that fail more than half the time\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'fail>50%' --sort fail_rate --sort-dir desc\n```\n\n## Show failed tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed' --sort outcome --sort-dir desc\n```\n\n## Show regressions\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:regressed'\n```\n\n## Show all currently broken tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'status:(failed, regressed)' --sort outcome --sort-dir desc\n```\n\n## Show flaked tests (passed on retry)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:flaked' --sort flip_rate --sort-dir desc\n```\n\n## Find slow tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'd>5s' --sort duration --sort-dir desc\n```\n\n## Find tests by error text\n\n```bash\nflakiness list tests --project myorg/myproject --fql '$timeout'\nflakiness list tests --project myorg/myproject --fql '$\"network error\"'\n```\n\n## Combine filters\n\nFailed tests in e2e files, excluding smoke-tagged tests:\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed f:e2e -#smoke'\n```\n\n## Narrow to a specific file\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'f:login.spec.ts'\n```\n\n## Find tests with a specific annotation\n\n```bash\nflakiness list tests --project myorg/myproject --fql '@skip'\nflakiness list tests --project myorg/myproject --fql '@fixme'\n```\n\n## Filter by environment\n\n### Show tests for a specific OS\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\"\n```\n\n### Show tests for a specific environment name\n\n```bash\nflakiness list tests --project myorg/myproject --env-name chromium\n```\n\n### Show tests for a specific architecture\n\n```bash\nflakiness list tests --project myorg/myproject --env-arch arm64\n```\n\n### Show tests for multiple OSes (OR)\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\"\n```\n\n### Combine env filter with FQL\n\nFailed tests on Linux only:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --fql 's:failed'\n```\n\n### Filter by user-supplied metadata\n\n```bash\nflakiness list tests --project myorg/myproject --env-metadata browser=firefox\n```\n\n### Combine multiple env filters (AND)\n\nTests on Linux with arm64 architecture:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-arch arm64\n```\n"
+        "content": "# Investigation Recipes\n\nReplace `myorg/myproject` with the target project slug, or set `FLAKINESS_PROJECT`.\n\n## Query a pull request\n\nShows tests from the merge-commit of the PR branch into the target branch.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42\n```\n\n## Find PR regressions (caused by the PR)\n\nTests marked `regressed` were passing on the target branch but fail in this PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:regressed'\n```\n\n## Find pre-existing failures in a PR\n\nTests marked `failed` also fail on the target branch \u2014 not caused by the PR.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 's:failed'\n```\n\n## Find all broken tests in a PR\n\nIncludes both PR-caused regressions and pre-existing failures.\n\n```bash\nflakiness list tests --project myorg/myproject --pr 42 --fql 'status:(failed, regressed)' --page-size 50\n```\n\n## Query a specific branch\n\nShows tests from the day of the branch's head commit, in the project's timezone.\n\n```bash\nflakiness list tests --project myorg/myproject --branch feature/login\n```\n\n## Find all flaky tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n## Find the most flaky tests (>50% flip rate)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'flip>50%' --sort flip_rate --sort-dir desc\n```\n\n## Find tests that have ever failed (terminal failure, retries exhausted)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'fail>0%' --sort fail_rate --sort-dir desc\n```\n\n## Find tests that fail more than half the time\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'fail>50%' --sort fail_rate --sort-dir desc\n```\n\n## Show failed tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed' --sort outcome --sort-dir desc\n```\n\n## Show regressions\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:regressed'\n```\n\n## Show all currently broken tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'status:(failed, regressed)' --sort outcome --sort-dir desc\n```\n\n## Show flaked tests (passed on retry)\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:flaked' --sort flip_rate --sort-dir desc\n```\n\n## Find slow tests\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'd>5s' --sort duration --sort-dir desc\n```\n\n## Find tests by error text\n\n```bash\nflakiness list tests --project myorg/myproject --fql '$timeout'\nflakiness list tests --project myorg/myproject --fql '$\"network error\"'\n```\n\n## Combine filters\n\nFailed tests in e2e files, excluding smoke-tagged tests:\n\n```bash\nflakiness list tests --project myorg/myproject --fql 's:failed f:e2e -#smoke'\n```\n\n## Narrow to a specific file\n\n```bash\nflakiness list tests --project myorg/myproject --fql 'f:login.spec.ts'\n```\n\n## Find tests with a specific annotation\n\n```bash\nflakiness list tests --project myorg/myproject --fql '@skip'\nflakiness list tests --project myorg/myproject --fql '@fixme'\n```\n\n## Filter by environment\n\n### Show tests for a specific OS\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\"\n```\n\n### Show tests for a specific environment name\n\n```bash\nflakiness list tests --project myorg/myproject --env-name chromium\n```\n\n### Show tests for a specific architecture\n\n```bash\nflakiness list tests --project myorg/myproject --env-arch arm64\n```\n\n### Show tests for multiple OSes (OR)\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-os \"Darwin 24.0\"\n```\n\n### Combine env filter with FQL\n\nFailed tests on Linux only:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --fql 's:failed'\n```\n\n### Filter by user-supplied metadata\n\n```bash\nflakiness list tests --project myorg/myproject --env-metadata browser=firefox\n```\n\n### Combine multiple env filters (AND)\n\nTests on Linux with arm64 architecture:\n\n```bash\nflakiness list tests --project myorg/myproject --env-os \"Ubuntu 22.04\" --env-arch arm64\n```\n\n## Review performance over time (day history)\n\nBucket history by day instead of by commit so duration trends and flip/fail rates read as a smooth day-over-day time series.\n\n### Tests getting slower over time\n\n```bash\nflakiness list tests --project myorg/myproject --history day --sort duration_trend --sort-dir desc\n```\n\n### Recurring flakes, day over day\n\n```bash\nflakiness list tests --project myorg/myproject --history day --fql 'flip>0%' --sort flip_rate --sort-dir desc\n```\n\n### Force per-commit history (override a project default of `day`)\n\n```bash\nflakiness list tests --project myorg/myproject --history commit\n```\n"
       }
     ]
   }
@@ -2333,6 +2337,7 @@ var optTestsPR = new Option("--pr <number>", "Show tests from a specific pull re
   return parsed;
 }).conflicts("branch");
 var optTestsBranch = new Option("--branch <name>", "Show tests from a specific branch").conflicts("pr");
+var optTestsHistory = new Option("--history <granularity>", "History granularity for trends, flip/fail rates, and the history column: per `commit` or per `day` (defaults to the project setting)").choices(["commit", "day"]);
 function collectValues(value, prev) {
   return [...prev ?? [], value];
 }
@@ -2346,7 +2351,7 @@ var optTestsEnvMetadata = new Option("--env-metadata <key=value>", "Filter by us
     throw new Error(`Invalid env-metadata format '${value}'; expected key=value`);
   return [...prev ?? [], value];
 });
-list.command("tests").description("Query tests data. Defaults to the default branch (day of head commit in project timezone). Use --pr for PR merge-commit tests, or --branch for a named branch.").addOption(optTestsPage).addOption(optTestsPageSize).addOption(optTestsSort).addOption(optTestsSortDir).addOption(optTestsFQL).addOption(optTestsPR).addOption(optTestsBranch).addOption(optTestsEnvName).addOption(optTestsEnvPath).addOption(optTestsEnvCategory).addOption(optTestsEnvOs).addOption(optTestsEnvArch).addOption(optTestsEnvMetadata).addOption(mustFlakinessProject).addOption(optEndpoint).addOption(optAccessToken).action(async (options) => runCommand(async () => {
+list.command("tests").description("Query tests data. Defaults to the default branch (day of head commit in project timezone). Use --pr for PR merge-commit tests, or --branch for a named branch.").addOption(optTestsPage).addOption(optTestsPageSize).addOption(optTestsSort).addOption(optTestsSortDir).addOption(optTestsFQL).addOption(optTestsPR).addOption(optTestsBranch).addOption(optTestsHistory).addOption(optTestsEnvName).addOption(optTestsEnvPath).addOption(optTestsEnvCategory).addOption(optTestsEnvOs).addOption(optTestsEnvArch).addOption(optTestsEnvMetadata).addOption(mustFlakinessProject).addOption(optEndpoint).addOption(optAccessToken).action(async (options) => runCommand(async () => {
   await cmdListTests({
     page: options.page,
     pageSize: options.pageSize,
@@ -2355,6 +2360,7 @@ list.command("tests").description("Query tests data. Defaults to the default bra
     fql: options.fql,
     pr: options.pr,
     branch: options.branch,
+    history: options.history,
     envName: options.envName,
     envPath: options.envPath,
     envCategory: options.envCategory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flakiness",
-  "version": "0.277.0",
+  "version": "0.279.0",
   "private": false,
   "bin": {
     "flakiness": "./lib/cli/cli.js"
@@ -19,12 +19,12 @@
   "author": "Degu Labs, Inc",
   "license": "MIT",
   "devDependencies": {
-    "@playwright/test": "^1.60.0",
+    "@playwright/test": "^1.61.0",
     "@types/debug": "^4.1.13",
     "@types/express": "^4.17.25",
     "gray-matter": "^4.0.3",
-    "@flakiness/server": "0.277.0",
-    "@flakiness/shared": "0.277.0"
+    "@flakiness/server": "0.279.0",
+    "@flakiness/shared": "0.279.0"
   },
   "dependencies": {
     "@flakiness/flakiness-report": "^0.34.0",