Skip to content

Commit e8ac3e6

Browse files
Googlercopybara-github
Googler
authored and
copybara-github
committed
Update documentation for expect_true, expect_false, assert_pred and expect_pred macros, which accept formatting args.
PiperOrigin-RevId: 737999810
1 parent a10bd6b commit e8ac3e6

9 files changed

+405
-2
lines changed

‎googletest/src/assertions.rs

+203
Original file line numberDiff line numberDiff line change
@@ -484,6 +484,29 @@ pub use verify_true;
484484
/// println!("This will print");
485485
/// }
486486
/// ```
487+
///
488+
/// One may optionally add arguments which will be formatted and appended to a
489+
/// failure message. For example:
490+
///
491+
/// ```ignore
492+
/// use googletest::prelude::*;
493+
///
494+
/// #[gtest]
495+
/// fn should_fail() {
496+
/// let extra_information = "Some additional information";
497+
/// expect_true!(false, "Test failed. Extra information: {extra_information}.");
498+
/// }
499+
/// ```
500+
///
501+
/// The output is as follows:
502+
///
503+
/// ```text
504+
/// Value of: false
505+
/// Expected: is equal to true
506+
/// Actual: false,
507+
/// which isn't equal to true
508+
/// Test failed. Extra information: Some additional information.
509+
/// ```
487510
#[macro_export]
488511
macro_rules! expect_true {
489512
($condition:expr) => {{
@@ -550,6 +573,29 @@ pub use verify_false;
550573
/// println!("This will print");
551574
/// }
552575
/// ```
576+
///
577+
/// One may optionally add arguments which will be formatted and appended to a
578+
/// failure message. For example:
579+
///
580+
/// ``` ignore
581+
/// use googletest::prelude::*;
582+
///
583+
/// #[gtest]
584+
/// fn should_fail() {
585+
/// let extra_information = "Some additional information";
586+
/// expect_false!(true, "Test failed. Extra information: {extra_information}.");
587+
/// }
588+
/// ```
589+
///
590+
/// The output is as follows:
591+
///
592+
/// ```text
593+
/// Value of: true
594+
/// Expected: is equal to false
595+
/// Actual: true,
596+
/// which isn't equal to false
597+
/// Test failed. Extra information: Some additional information.
598+
/// ```
553599
#[macro_export]
554600
macro_rules! expect_false {
555601
($condition:expr) => {{
@@ -1405,6 +1451,26 @@ pub use assert_that;
14051451
/// Asserts that the given predicate applied to the given arguments returns
14061452
/// true, panicking if it does not.
14071453
///
1454+
/// One may optionally add arguments which will be formatted and appended to a
1455+
/// failure message. For example:
1456+
///
1457+
/// ```should_panic
1458+
/// use googletest::prelude::*;
1459+
///
1460+
/// #[gtest]
1461+
/// fn should_fail() {
1462+
/// let extra_information = "Some additional information";
1463+
/// assert_pred!(1 == 2, "Test failed. Extra information: {extra_information}.");
1464+
/// }
1465+
/// ```
1466+
///
1467+
/// The output is as follows:
1468+
///
1469+
/// ```text
1470+
/// 1 == 2 was false with
1471+
/// Test failed. Extra information: Some additional information.
1472+
/// ```
1473+
///
14081474
/// **Note for users of [GoogleTest for C++](http://google.github.io/googletest/):**
14091475
/// This differs from the `ASSERT_PRED*` family of macros in that it panics
14101476
/// rather than triggering an early return from the invoking function. To get
@@ -1536,6 +1602,26 @@ pub use expect_that;
15361602
/// ```ignore
15371603
/// verify_pred!(predicate(...)).and_log_failure()
15381604
/// ```
1605+
///
1606+
/// One may optionally add arguments which will be formatted and appended to a
1607+
/// failure message. For example:
1608+
///
1609+
/// ```ignore
1610+
/// use googletest::prelude::*;
1611+
///
1612+
/// #[gtest]
1613+
/// fn should_fail() {
1614+
/// let extra_information = "Some additional information";
1615+
/// expect_pred!(1 == 2, "Test failed. Extra information: {extra_information}.");
1616+
/// }
1617+
/// ```
1618+
///
1619+
/// The output is as follows:
1620+
///
1621+
/// ```text
1622+
/// 1 == 2 was false with
1623+
/// Test failed. Extra information: Some additional information.
1624+
/// ```
15391625
#[macro_export]
15401626
macro_rules! expect_pred {
15411627
($content:expr $(,)?) => {{
@@ -1550,6 +1636,123 @@ macro_rules! expect_pred {
15501636
}
15511637
pub use expect_pred;
15521638

1639+
/// Matches the given expr Result against the Result::Ok(anything()) matcher,
1640+
/// marking the test as failed but continuing execution if it does not match.
1641+
///
1642+
/// This is a *non-fatal* assertion: the test continues
1643+
/// execution in the event of assertion failure.
1644+
///
1645+
/// This can only be invoked inside tests with the
1646+
/// [`gtest`][crate::gtest] attribute. The assertion must
1647+
/// occur in the same thread as that running the test itself.
1648+
///
1649+
/// Invoking this macro is equivalent to using
1650+
/// [`and_log_failure`](crate::GoogleTestSupport::and_log_failure) as follows:
1651+
///
1652+
/// ```ignore
1653+
/// verify_that!(actual, ok(anything())).and_log_failure()
1654+
/// ```
1655+
///
1656+
/// One may optionally add arguments which will be formatted and appended to a
1657+
/// failure message. For example:
1658+
///
1659+
/// ```
1660+
/// # use googletest::prelude::*;
1661+
/// # fn should_fail() -> std::result::Result<(), googletest::internal::test_outcome::TestFailure> {
1662+
/// # googletest::internal::test_outcome::TestOutcome::init_current_test_outcome();
1663+
/// let extra_information = "Some additional information";
1664+
/// expect_ok!(Err::<&str, _>("An error"), "Test failed. Extra information: {extra_information}.");
1665+
/// # googletest::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
1666+
/// # }
1667+
/// # should_fail().unwrap_err();
1668+
/// ```
1669+
///
1670+
/// This is output as follows:
1671+
///
1672+
/// ```text
1673+
/// Value of: Err::<&str, _>("An error")
1674+
/// Expected: is a success containing a value, which is anything
1675+
/// Actual: Err("An error"),
1676+
/// which is an error
1677+
/// Test failed. Extra information: Some additional information.
1678+
/// ```
1679+
#[macro_export]
1680+
macro_rules! expect_ok {
1681+
($actual:expr $(,)?) => {{
1682+
$crate::GoogleTestSupport::and_log_failure($crate::verify_that!($actual, $crate::matchers::ok(anything())));
1683+
}};
1684+
// w/ format args
1685+
($actual:expr, $($format_args:expr),* $(,)?) => {{
1686+
$crate::GoogleTestSupport::and_log_failure($crate::verify_that!($actual, $crate::matchers::ok(anything()))
1687+
.with_failure_message(|| format!($($format_args),*))
1688+
);
1689+
}};
1690+
}
1691+
pub use expect_ok;
1692+
1693+
/// Matches the given expr Result against the Result::Ok(anything()) matcher,
1694+
/// panicking if it does not match.
1695+
///
1696+
/// ```should_panic
1697+
/// # use googletest::prelude::*;
1698+
/// # fn should_fail() {
1699+
/// assert_ok!(Err::<&str, _>("An error")); // Fails and panics.
1700+
/// # }
1701+
/// # should_fail();
1702+
/// ```
1703+
///
1704+
/// This is analogous to assertions in most Rust test libraries, where a failed
1705+
/// assertion causes a panic.
1706+
///
1707+
/// One may optionally add arguments which will be formatted and appended to a
1708+
/// failure message. For example:
1709+
///
1710+
/// ```should_panic
1711+
/// # use googletest::prelude::*;
1712+
/// # fn should_fail() {
1713+
/// let extra_information = "Some additional information";
1714+
/// assert_ok!(Err::<&str, _>("An error"), "Test failed. Extra information: {extra_information}.");
1715+
/// # }
1716+
/// # should_fail();
1717+
/// ```
1718+
///
1719+
/// This is output as follows:
1720+
///
1721+
/// ```text
1722+
/// Value of: Err::<&str, _>("An error")
1723+
/// Expected: is a success containing a value, which is anything
1724+
/// Actual: Err("An error"),
1725+
/// which is an error
1726+
/// Test failed. Extra information: Some additional information.
1727+
/// ```
1728+
#[macro_export]
1729+
macro_rules! assert_ok {
1730+
($actual:expr $(,)?) => {
1731+
match $crate::verify_that!($actual, $crate::matchers::ok(anything())) {
1732+
Ok(_) => {}
1733+
Err(e) => {
1734+
// The extra newline before the assertion failure message makes the failure a
1735+
// bit easier to read when there's some generic boilerplate from the panic.
1736+
panic!("\n{}", e);
1737+
}
1738+
}
1739+
};
1740+
// w/ format args
1741+
($actual:expr, $($format_args:expr), * $(,)?) => {
1742+
match $crate::verify_that!($actual, $crate::matchers::ok(anything()))
1743+
.with_failure_message(|| format!($($format_args),*))
1744+
{
1745+
Ok(_) => {}
1746+
Err(e) => {
1747+
// The extra newline before the assertion failure message makes the failure a
1748+
// bit easier to read when there's some generic boilerplate from the panic.
1749+
panic!("\n{}", e);
1750+
}
1751+
}
1752+
};
1753+
}
1754+
pub use assert_ok;
1755+
15531756
/// Functions for use only by the procedural macros in this module.
15541757
///
15551758
/// **For internal use only. API stablility is not guaranteed!**

‎googletest/src/lib.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,9 @@ pub mod prelude {
5757
pub use super::Result;
5858
// Assert macros
5959
pub use super::{
60-
add_failure, add_failure_at, assert_pred, assert_that, expect_eq, expect_false,
60+
add_failure, add_failure_at, assert_ok, assert_pred, assert_that, expect_eq, expect_false,
6161
expect_float_eq, expect_ge, expect_gt, expect_le, expect_lt, expect_ne, expect_near,
62-
expect_pred, expect_that, expect_true, fail, succeed, verify_eq, verify_false,
62+
expect_ok, expect_pred, expect_that, expect_true, fail, succeed, verify_eq, verify_false,
6363
verify_float_eq, verify_ge, verify_gt, verify_le, verify_lt, verify_ne, verify_near,
6464
verify_pred, verify_that, verify_true,
6565
};

‎integration_tests/Cargo.toml

+20
Original file line numberDiff line numberDiff line change
@@ -449,4 +449,24 @@ test = false
449449
[[bin]]
450450
name = "expect_pred_macro_on_assertion_failure_with_format_args"
451451
path = "src/expect_pred_macro_on_assertion_failure_with_format_args.rs"
452+
test = false
453+
454+
[[bin]]
455+
name = "expect_ok_when_error_marks_failed"
456+
path = "src/expect_ok_when_error_marks_failed.rs"
457+
test = false
458+
459+
[[bin]]
460+
name = "expect_ok_when_error_supports_custom_error_message"
461+
path = "src/expect_ok_when_error_supports_custom_error_message.rs"
462+
test = false
463+
464+
[[bin]]
465+
name = "assert_ok_when_error_marks_failed"
466+
path = "src/assert_ok_when_error_marks_failed.rs"
467+
test = false
468+
469+
[[bin]]
470+
name = "assert_ok_when_error_supports_custom_error_message"
471+
path = "src/assert_ok_when_error_supports_custom_error_message.rs"
452472
test = false

‎integration_tests/src/assert_ok_when_error_marks_failed.rs

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// Copyright 2025 Google LLC
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+
fn main() {}
16+
17+
#[cfg(test)]
18+
mod tests {
19+
use googletest::prelude::*;
20+
21+
#[gtest]
22+
fn should_fail() {
23+
assert_ok!(Err::<&str, _>("An error"))
24+
}
25+
}

‎integration_tests/src/assert_ok_when_error_supports_custom_error_message.rs

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Copyright 2025 Google LLC
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+
fn main() {}
16+
17+
#[cfg(test)]
18+
mod tests {
19+
use googletest::prelude::*;
20+
21+
#[gtest]
22+
fn should_fail() {
23+
let extra_information = "extra information";
24+
assert_ok!(Err::<&str, _>("An error"), "expected success: {extra_information}.")
25+
}
26+
}

‎integration_tests/src/expect_ok_when_error_marks_failed.rs

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// Copyright 2025 Google LLC
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+
fn main() {}
16+
17+
#[cfg(test)]
18+
mod tests {
19+
use googletest::prelude::*;
20+
21+
#[gtest]
22+
fn should_fail() {
23+
expect_ok!(Err::<&str, _>("An error"));
24+
}
25+
}

‎integration_tests/src/expect_ok_when_error_supports_custom_error_message.rs

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Copyright 2025 Google LLC
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+
fn main() {}
16+
17+
#[cfg(test)]
18+
mod tests {
19+
use googletest::prelude::*;
20+
21+
#[gtest]
22+
fn should_fail() {
23+
let extra_information = "extra information";
24+
expect_ok!(Err::<&str, _>("An error"), "expected success: {extra_information}.");
25+
}
26+
}

0 commit comments

Comments
 (0)