Bazel Knowledge Hub

1.2.2 Test Sizes & Timeouts

size and timeout are the two pieces of metadata that tell Bazel how expensive a test is and how long it may run. Unlike 1.2.1 Test Caching, they matter only when Bazel executes the test, but when that happens they shape the default deadline, local scheduling, and the metadata later CI policies depend on1,2,3.

Test size and implied timeout
If you omit timeout, Bazel picks the deadline from size (default medium → moderate)
SIZE
IMPLIED TIMEOUT
small
→
short
medium
→
moderate
large
→
long
enormous
→
eternal
Any size / timeout pair is legal. An explicit timeout = … overrides the deadline without changing heaviness.
SIZE
How heavy is local execution?
Scheduling and reservation
size = "large"
TIMEOUT
How long may the test run?
Enforced kill deadline
timeout = "long"
Set size to the test's expected resource use. Set timeout only when its default deadline is unsuitable.

size and timeout control different things

Like other target metadata from 0.3.3 Attributes & Semantic Roles, both live in the test rule declaration. Bazel has four size labels - small, medium, large, enormous - and four timeout labels - short, moderate, long, eternal1.

sizeimplied timeout
smallshort
mediummoderate
largelong
enormouseternal

If you omit timeout, Bazel infers it from size. If you omit size entirely, the test defaults to medium, which in practice means a moderate timeout unless you override it1,2.

size carries information beyond timeout. All size/timeout combinations are legal, so a test can be size = "small" with timeout = "long" if it is light on local resources but legitimately slow1,2.

size carries scheduling information

timeout is the deadline Bazel enforces. size does more: it also tells Bazel how heavy the test is for local execution, especially when Bazel is deciding how many tests can run concurrently on the machine1,3,4,5.

Choose each attribute for its own job:

  • choose size for rough cost,
  • use explicit timeout only when the implied deadline is wrong.

size = "large" implies a longer timeout and more local RAM reservation, while timeout = "long" changes only the deadline4. If a test routinely causes local memory pressure, lying about its size teaches Bazel's scheduler the wrong lesson5.

Use size for cost, tags for behavior

Teams often map small, medium, large, and enormous roughly onto unit, integration, and end-to-end testing in day-to-day conversation, but Bazel itself treats them as execution metadata, not as a semantic taxonomy1,3. For behavioral switches such as manual, exclusive, or flaky, use the tags explained in 1.2.3 Test Tags instead.

The fixes differ by layer. If a target is expensive but structurally still one test, declare its size honestly. If the target needs special execution behavior, use tags. If one target has become too big for one process, the next tool is usually 1.2.5 Test Sharding, not an endlessly inflated timeout1.

This metadata is useful from the CLI

Because size and timeout live on the target, Bazel can filter on them directly:

bazel test --test_size_filters=-large,-enormous //foo:all
bazel test --test_timeout_filters=-eternal //foo:all

That makes the metadata operational, not decorative. A fast local smoke-test loop can exclude heavyweight tests, while later CI policy can combine the same signals with graph analysis in 6.5.1 Affected-Target Service Contract and H.7.3 Evidence Selection, then stage them differently between pre-submit and post-submit runs in H.7.4 Change Admission2. When you need a temporary local override, --test_timeout=120 changes the timeout in seconds without editing BUILD files1,2. Repo-wide defaults for these flags belong in .bazelrc, which returns in 3.2 Project Configuration.

recommended

Enable test --test_verbose_timeout_warnings as the suite grows. Bazel will warn when declared sizes or timeouts look too generous, surfacing tests that silently became slower over time1,3. Inflated sizes hide regressions. Undersized ones produce noisy failures.

key takeaway

size answers "how heavy is this test for Bazel to run locally?" timeout answers "how long may it run before Bazel kills it?" Most of the time, declaring the smallest honest size is enough because Bazel will infer the timeout. Reach for explicit timeout only when the default deadline is wrong.

Check your understanding · 3 questions

1.Match each test size to its default (implied) timeout category:

Drag each answer onto the matching prompt, or click an answer and then click a prompt

Answers
small
medium
large
enormous

2.True or false: what does the test size attribute influence?

Choose True or False for each sentence

The size attribute only controls the test's timeout deadline — it has no effect on local scheduling.
size reserves local resources, which influences how many tests Bazel runs concurrently.
size decides whether the test is included in wildcard patterns like //...
size determines the programming language used to compile the test binary.

3.An operator wants a fast local smoke-test loop that excludes heavyweight tests, while CI keeps running everything. What is the standard way to express that locally without editing BUILD files?

Select one answer

0 of 3 answered

Footnotes

  1. Test encyclopedia — timeout categories, size-to-timeout mapping, default medium size, legal size/timeout combinations, --test_timeout, and timeout-warning guidance ↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9

  2. Commands and Options — --test_size_filters, --test_timeout_filters, --test_timeout, and the rule that explicit timeout can differ from the test's size ↩1 ↩2 ↩3 ↩4 ↩5

  3. How to set up a Bazel testing configuration: comprehensive guide for Scala and Java — operator-facing explanation of test size as "heaviness", local scheduling impact, and practical timeout calibration ↩1 ↩2 ↩3 ↩4

  4. Bazel Training 101 (Part 15): Flags and Tags — concise distinction between size implying more RAM plus timeout and timeout changing only the deadline ↩1 ↩2

  5. Fixing Bazel out-of-memory problems — why honest test_size metadata matters for local memory reservation and action scheduling ↩1 ↩2

← PreviousTest CachingNext →Test Tags