flakiness 0.304.0 → 0.306.0

package/lib/cli/cli.js

@@ -983,9 +983,51 @@ var TestOutcomes;
   TestOutcomes2.formatCounts = formatCounts;
 })(TestOutcomes || (TestOutcomes = {}));
 
+// ../server/lib/common/timePeriod.js
+var TimePeriod;
+((TimePeriod2) => {
+  TimePeriod2.PERIODS = ["3h", "day", "usweek", "monthweek", "month", "quarter"];
+  const LENGTHS = {
+    "3h": { hours: 3 },
+    day: { days: 1 },
+    usweek: { weeks: 1 },
+    month: { months: 1 },
+    quarter: { months: 3 }
+  };
+  function periodStart(period, time) {
+    if (period === "3h")
+      return time.round({ smallestUnit: "hour", roundingIncrement: 3, roundingMode: "floor" });
+    const day = time.toPlainDate();
+    if (period === "day")
+      return day.toPlainDateTime();
+    if (period === "usweek")
+      return day.subtract({ days: day.dayOfWeek % 7 }).toPlainDateTime();
+    if (period === "monthweek")
+      return day.with({ day: Math.min(Math.floor((day.day - 1) / 7), 3) * 7 + 1 }).toPlainDateTime();
+    if (period === "month")
+      return day.with({ day: 1 }).toPlainDateTime();
+    return day.with({ month: Math.floor((day.month - 1) / 3) * 3 + 1, day: 1 }).toPlainDateTime();
+  }
+  TimePeriod2.periodStart = periodStart;
+  function periodEnd(period, time) {
+    const start = periodStart(period, time);
+    if (period === "monthweek")
+      return start.day < 22 ? start.add({ days: 7 }) : periodEnd("month", start);
+    return start.add(LENGTHS[period]);
+  }
+  TimePeriod2.periodEnd = periodEnd;
+  function lastDay(until) {
+    return until.subtract({ nanoseconds: 1 }).toPlainDate();
+  }
+  TimePeriod2.lastDay = lastDay;
+})(TimePeriod || (TimePeriod = {}));
+
 // ../server/lib/common/wireTypes.js
 var WireTypes;
 ((WireTypes2) => {
+  WireTypes2.OUTCOME_CLASSIFICATIONS = ["eod", "worst"];
+  WireTypes2.HISTORY_TYPES = ["commit", ...TimePeriod.PERIODS];
+  WireTypes2.ANALYTICS_OUTCOMES = ["expected", "unexpected", "flaked", "skipped"];
   WireTypes2.SORT_AXES = {
     tests: [
       "name",
@@ -1054,11 +1096,12 @@ import { Command, Option } from "commander";
 import debug2 from "debug";
 import fs7 from "fs";
 import path7 from "path";
+import { Temporal as Temporal2 } from "temporal-polyfill";
 
 // ../package.json
 var package_default = {
   name: "@flakiness/monorepo",
-  version: "0.304.0",
+  version: "0.306.0",
   type: "module",
   private: true,
   scripts: {
@@ -2080,8 +2123,8 @@ async function cmdListTests(options) {
   let preset;
   if (options.pr !== void 0)
     preset = { type: "pr", number: options.pr };
-  else if (options.branch !== void 0)
-    preset = { type: "branch", name: options.branch };
+  else if (options.branch !== void 0 || options.day !== void 0)
+    preset = { type: "branch", name: options.branch, day: options.day };
   const result = await api.report.testStats.POST({
     orgSlug,
     projectSlug,
@@ -2106,6 +2149,8 @@ async function cmdListTests(options) {
     scope = `PR #${options.pr}`;
   else if (options.branch !== void 0)
     scope = `branch \`${options.branch}\``;
+  if (options.day !== void 0)
+    scope += `, ${options.day}`;
   const lines = [
     `# Tests for \`${orgSlug}/${projectSlug}\` (${scope})`,
     "",
@@ -2217,7 +2262,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>] [--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"
+        "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>] [--day <YYYY-MM-DD>] [--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| `--day <YYYY-MM-DD>` | A specific calendar day, in the project's timezone. Combine with `--branch`, or use alone for the default branch. |\n\n`--pr` is mutually exclusive with both `--branch` and `--day`: a PR query is pinned to the PR's last tested commit, so a day has no meaning there.\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",
@@ -2225,7 +2270,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\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"
+        "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## Query a specific day\n\nThe day is a calendar day in the project's timezone. Without `--branch` it applies to the default branch.\n\n```bash\nflakiness list tests --project myorg/myproject --day 2026-09-16\nflakiness list tests --project myorg/myproject --branch feature/login --day 2026-09-16\n```\n\nTo compare a test's behaviour across days, run the same query for each day and diff the results.\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"
       }
     ]
   }
@@ -2358,6 +2403,16 @@ 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 optTestsDay = new Option("--day <YYYY-MM-DD>", "Show tests from a specific day, in the project timezone (defaults to the day of the branch head commit)").argParser((value) => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+    throw new Error("day must be a YYYY-MM-DD date, e.g. 2026-09-17");
+  try {
+    Temporal2.PlainDate.from(value, { overflow: "reject" });
+  } catch {
+    throw new Error(`'${value}' is not a valid calendar date`);
+  }
+  return value;
+}).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];
@@ -2372,7 +2427,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(optTestsHistory).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, and --day to pick a day.").addOption(optTestsPage).addOption(optTestsPageSize).addOption(optTestsSort).addOption(optTestsSortDir).addOption(optTestsFQL).addOption(optTestsPR).addOption(optTestsBranch).addOption(optTestsDay).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,
@@ -2381,6 +2436,7 @@ list.command("tests").description("Query tests data. Defaults to the default bra
     fql: options.fql,
     pr: options.pr,
     branch: options.branch,
+    day: options.day,
     history: options.history,
     envName: options.envName,
     envPath: options.envPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flakiness",
-  "version": "0.304.0",
+  "version": "0.306.0",
   "private": false,
   "bin": {
     "flakiness": "./lib/cli/cli.js"
@@ -19,8 +19,8 @@
   "author": "Degu Labs, Inc",
   "license": "MIT",
   "devDependencies": {
-    "@flakiness/server": "0.304.0",
-    "@flakiness/shared": "0.304.0",
+    "@flakiness/server": "0.306.0",
+    "@flakiness/shared": "0.306.0",
     "@playwright/test": "^1.62.1",
     "@types/debug": "^4.1.13",
     "@types/express": "^4.17.25",