1# Copyright 2023 The Bazel Authors. All rights reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15"""# Truth 16 17Truth-style asserts for Bazel's Starlark. 18 19These asserts follow the Truth-style way of performing assertions. This 20basically means the actual value is wrapped in a type-specific object that 21provides type-specific assertion methods. This style provides several benefits: 22 * A fluent API that more directly expresses the assertion 23 * More egonomic assert functions 24 * Error messages with more informative context 25 * Promotes code reuses at the type-level. 26 27For more detailed documentation, see the docs on GitHub. 28 29## Basic usage 30 31NOTE: This example assumes usage of [`rules_testing`]'s [`analysis_test`] 32framework, but that framework is not required. 33 34``` 35def foo_test(env, target): 36 subject = env.expect.that_target(target) 37 subject.runfiles().contains_at_least(["foo.txt"]) 38 subject.executable().equals("bar.exe") 39 40 subject = env.expect.that_action(...) 41 subject.contains_at_least_args(...) 42``` 43""" 44 45load("//lib/private:bool_subject.bzl", "BoolSubject") 46load("//lib/private:collection_subject.bzl", "CollectionSubject") 47load("//lib/private:default_info_subject.bzl", "DefaultInfoSubject") 48load("//lib/private:depset_file_subject.bzl", "DepsetFileSubject") 49load("//lib/private:dict_subject.bzl", "DictSubject") 50load("//lib/private:expect.bzl", "Expect") 51load("//lib/private:file_subject.bzl", "FileSubject") 52load("//lib/private:int_subject.bzl", "IntSubject") 53load("//lib/private:label_subject.bzl", "LabelSubject") 54load("//lib/private:runfiles_subject.bzl", "RunfilesSubject") 55load("//lib/private:str_subject.bzl", "StrSubject") 56load("//lib/private:target_subject.bzl", "TargetSubject") 57load("//lib/private:matching.bzl", _matching = "matching") 58load("//lib/private:struct_subject.bzl", "StructSubject") 59 60# Rather than load many symbols, just load this symbol, and then all the 61# asserts will be available. 62truth = struct( 63 expect = Expect.new_from_env, 64) 65 66# For the definition of a `Matcher` object, see `_match_custom`. 67matching = _matching 68 69subjects = struct( 70 # keep sorted start 71 bool = BoolSubject.new, 72 collection = CollectionSubject.new, 73 default_info = DefaultInfoSubject.new, 74 depset_file = DepsetFileSubject.new, 75 dict = DictSubject.new, 76 file = FileSubject.new, 77 int = IntSubject.new, 78 label = LabelSubject.new, 79 runfiles = RunfilesSubject.new, 80 str = StrSubject.new, 81 struct = StructSubject.new, 82 target = TargetSubject.new, 83 # keep sorted end 84) 85