Testing

How to run, write, and structure tests.

Test runners

Everything is driven through Bazel. Tests are co-located with the code they test:

tensorflow/core/kernels/matmul_op.cc
tensorflow/core/kernels/matmul_op_test.cc          ← C++ test for that kernel

tensorflow/python/ops/math_ops.py
tensorflow/python/ops/math_ops_test.py             ← Python test for that file

bazel test //tensorflow/core/kernels:matmul_op_test
bazel test //tensorflow/python/ops:math_ops_test
bazel test //tensorflow/python/...                 # everything Python (slow!)

Useful flags:

• --test_tag_filters=-gpu,-no_oss — exclude GPU-only tests and Google-internal ones.
• --test_size_filters=small,medium — run only fast tests.
• --test_output=errors — only show failing test logs.
• --config=cuda — enable GPU tests; they are tagged gpu.

Python test framework

Python tests use tf.test.TestCase (tensorflow/python/framework/test_util.py) which extends absl.testing.parameterized.TestCase. The class adds:

• assertAllClose, assertAllEqual, assertShapeEqual — tensor-aware assertions.
• cached_session() — get a Session for tests that exercise graph mode.
• Decorators like @test_util.run_in_graph_and_eager_modes to run the same test under both modes.

Common test patterns live in tensorflow/python/framework/:

File	Purpose
tensorflow/python/framework/test_util.py	TestCase, mode decorators
tensorflow/python/framework/test_combinations.py	Generators for parameterized eager/graph/XLA combinations
tensorflow/python/keras/keras_parameterized.py	Keras-flavoured combinations
tensorflow/python/distribute/combinations.py	Distribution-strategy parameterizations

A typical Python kernel test runs an op in eager mode, runs the same op in a tf.function, and asserts equal outputs.

C++ test framework

C++ tests use GoogleTest + Google Test Bench. The tensorflow/core/framework/op_kernel.h and tensorflow/core/kernels/ops_testutil.h headers expose helpers:

• OpsTestBase — fixture that instantiates an op kernel with given inputs and runs it on the CPU.
• Tensor constructors that accept gtl::ArraySlice for inline data.

Most kernel tests build the op via NodeDefBuilder, attach inputs, run, and assert tensor values:

TEST_F(MatMulOpTest, Square) {
  TF_ASSERT_OK(NodeDefBuilder("matmul", "MatMul")
                   .Input(FakeInput(DT_FLOAT))
                   .Input(FakeInput(DT_FLOAT))
                   .Finalize(node_def()));
  TF_ASSERT_OK(InitOp());
  AddInputFromArray<float>(...);
  TF_ASSERT_OK(RunOpKernel());
  test::ExpectTensorEqual<float>(...);
}

GPU and TPU tests

• GPU tests are tagged gpu. CI runs them on Linux GPU images.
• TPU tests are tagged tpu and use TpuStrategy or in-process TPU stubs in tensorflow/python/tpu/.
• Tests that should not run on a particular platform can be tagged no_gpu, no_mac, no_windows, no_oss, etc.

Coverage and CI matrix

The CI matrix is described in README.md:

• Linux CPU, Linux GPU, Linux XLA
• macOS
• Windows CPU, Windows GPU
• Android, Raspberry Pi 0/1/2/3
• Libtensorflow binary builds on macOS, Linux CPU/GPU, Windows CPU/GPU.

Every PR is gated by a smaller subset; the full matrix runs internally. If a PR breaks, e.g., the Windows GPU build, expect a maintainer to revert via Copybara and ask you to resubmit.

Related

• debugging — tools for when tests fail.
• tooling — Bazel macros and code generators.