| use proc_macro2::TokenStream; |
| use quote::{format_ident, quote, quote_spanned, ToTokens}; |
| use syn::spanned::Spanned; |
| |
| /// The prefix attached to a Gtest factory function by the RUST_GTEST_TEST_SUITE_FACTORY() macro. |
| const RUST_GTEST_FACTORY_PREFIX: &str = "RustGtestFactory_"; |
| |
| /// The `gtest` macro can be placed on a function to make it into a Gtest unit test, when linked |
| /// into a C++ binary that invokes Gtest. |
| /// |
| /// The `gtest` macro takes two arguments, which are Rust identifiers. The first is the name of the |
| /// test suite and the second is the name of the test, each of which are converted to a string and |
| /// given to Gtest. The name of the test function itself does not matter, and need not be unique |
| /// (it's placed into a unique module based on the Gtest suite + test names. |
| /// |
| /// The test function must have no arguments. The return value must be either `()` or |
| /// `std::result::Result<(), E>`. If another return type is found, the test will fail when run. If |
| /// the return type is a `Result`, then an `Err` is treated as a test failure. |
| /// |
| /// # Examples |
| /// ``` |
| /// #[gtest(MathTest, Addition)] |
| /// fn my_test() { |
| /// expect_eq!(1 + 1, 2); |
| /// } |
| /// ``` |
| /// |
| /// The above adds the function to the Gtest binary as `MathTest.Addtition`: |
| /// ``` |
| /// [ RUN ] MathTest.Addition |
| /// [ OK ] MathTest.Addition (0 ms) |
| /// ``` |
| /// |
| /// A test with a Result return type, and which uses the `?` operator. It will fail if the test |
| /// returns an `Err`, and print the resulting error string: |
| /// ``` |
| /// #[gtest(ResultTest, CheckThingWithResult)] |
| /// fn my_test() -> std::result::Result<(), String> { |
| /// call_thing_with_result()?; |
| /// } |
| /// ``` |
| #[proc_macro_attribute] |
| pub fn gtest( |
| arg_stream: proc_macro::TokenStream, |
| input: proc_macro::TokenStream, |
| ) -> proc_macro::TokenStream { |
| enum GtestAttributeArgument { |
| TestSuite, |
| TestName, |
| } |
| // Returns a string representation of an identifier argument to the attribute. For example, for |
| // #[gtest(Foo, Bar)], this function would return "Foo" for position 0 and "Bar" for position 1. |
| // If the argument is not a Rust identifier or not present, it returns a compiler error as a |
| // TokenStream to be emitted. |
| fn get_arg_string( |
| args: &syn::AttributeArgs, |
| which: GtestAttributeArgument, |
| ) -> Result<String, TokenStream> { |
| let pos = match which { |
| GtestAttributeArgument::TestSuite => 0, |
| GtestAttributeArgument::TestName => 1, |
| }; |
| match &args[pos] { |
| syn::NestedMeta::Meta(syn::Meta::Path(path)) if path.segments.len() == 1 => { |
| Ok(path.segments[0].ident.to_string()) |
| } |
| _ => { |
| let error_stream = match which { |
| GtestAttributeArgument::TestSuite => { |
| quote_spanned! { |
| args[pos].span() => |
| compile_error!( |
| "Expected a test suite name, written as an identifier." |
| ); |
| } |
| } |
| GtestAttributeArgument::TestName => { |
| quote_spanned! { |
| args[pos].span() => |
| compile_error!( |
| "Expected a test name, written as an identifier." |
| ); |
| } |
| } |
| }; |
| Err(error_stream) |
| } |
| } |
| } |
| /// Parses `#[gtest_suite(path::to::RustType)]` and returns `path::to::RustType`. |
| fn parse_gtest_suite(attr: &syn::Attribute) -> Result<TokenStream, TokenStream> { |
| let parsed = match attr.parse_meta() { |
| Ok(syn::Meta::List(list)) if list.nested.len() == 1 => match &list.nested[0] { |
| syn::NestedMeta::Meta(syn::Meta::Path(fn_path)) => Ok(fn_path.into_token_stream()), |
| x => Err(x.span()), |
| }, |
| Ok(x) => Err(x.span()), |
| Err(x) => Err(x.span()), |
| }; |
| parsed.or_else(|span| { |
| Err(quote_spanned! { span => |
| compile_error!( |
| "invalid syntax for gtest_suite macro, \ |
| expected `#[gtest_suite(path::to:RustType)]`"); |
| }) |
| }) |
| } |
| |
| let args = syn::parse_macro_input!(arg_stream as syn::AttributeArgs); |
| let mut input_fn = syn::parse_macro_input!(input as syn::ItemFn); |
| |
| // Populated data from the #[gtest_suite] macro arguments. |
| // |
| // The Rust type wrapping a C++ TestSuite (subclass of `testing::Test`), which is created and |
| // returned by a C++ factory function. If no type is specified, then this is left as None, and |
| // the default C++ factory function will be used to make a `testing::Test` directly. |
| let mut gtest_test_suite_wrapper_type: Option<TokenStream> = None; |
| |
| // Look through other attributes on the test function, parse the ones related to Gtests, and put |
| // the rest back into `attrs`. |
| input_fn.attrs = { |
| let mut keep = Vec::new(); |
| for attr in std::mem::take(&mut input_fn.attrs) { |
| if attr.path.is_ident("gtest_suite") { |
| let rust_type_name = match parse_gtest_suite(&attr) { |
| Ok(tokens) => tokens, |
| Err(error_tokens) => return error_tokens.into(), |
| }; |
| gtest_test_suite_wrapper_type = Some(rust_type_name); |
| } else { |
| keep.push(attr) |
| } |
| } |
| keep |
| }; |
| |
| // No longer mut. |
| let input_fn = input_fn; |
| let gtest_test_suite_wrapper_type = gtest_test_suite_wrapper_type; |
| |
| if let Some(asyncness) = input_fn.sig.asyncness { |
| // TODO(crbug.com/1288947): We can support async functions once we have block_on() support |
| // which will run a RunLoop until the async test completes. The run_test_fn just needs to be |
| // generated to `block_on(|| #test_fn)` instead of calling `#test_fn` synchronously. |
| return quote_spanned! { |
| asyncness.span => |
| compile_error!("async functions are not supported."); |
| } |
| .into(); |
| } |
| |
| let (test_suite_name, test_name) = match args.len() { |
| 2 => { |
| let suite = match get_arg_string(&args, GtestAttributeArgument::TestSuite) { |
| Ok(ok) => ok, |
| Err(error_stream) => return error_stream.into(), |
| }; |
| let test = match get_arg_string(&args, GtestAttributeArgument::TestName) { |
| Ok(ok) => ok, |
| Err(error_stream) => return error_stream.into(), |
| }; |
| (suite, test) |
| } |
| 0 | 1 => { |
| return quote! { |
| compile_error!( |
| "Expected two arguments. For example: #[gtest(TestSuite, TestName)]."); |
| } |
| .into(); |
| } |
| x => { |
| return quote_spanned! { |
| args[x.min(2)].span() => |
| compile_error!( |
| "Expected two arguments. For example: #[gtest(TestSuite, TestName)]."); |
| } |
| .into(); |
| } |
| }; |
| |
| // We put the test function and all the code we generate around it into a submodule which is |
| // uniquely named for the super module based on the Gtest suite and test names. A result of this |
| // is that if two tests have the same test suite + name, a compiler error would report the |
| // conflict. |
| let test_mod = format_ident!("__test_{}_{}", test_suite_name, test_name); |
| |
| // The run_test_fn identifier is marked #[no_mangle] to work around a codegen bug where the |
| // function is seen as dead and the compiler omits it from the object files. Since it's |
| // #[no_mangle], the identifier must be globally unique or we have an ODR violation. To produce |
| // a unique identifier, we roll our own name mangling by combining the file name and path from |
| // the source tree root with the Gtest suite and test names and the function itself. |
| // |
| // Note that an adversary could still produce a bug here by placing two equal Gtest suite and |
| // names in a single .rs file but in separate inline submodules. |
| let mangled_function_name = |f: &syn::ItemFn| -> syn::Ident { |
| let file_name = file!().replace(|c: char| !c.is_ascii_alphanumeric(), "_"); |
| format_ident!("{}_{}_{}_{}", file_name, test_suite_name, test_name, f.sig.ident) |
| }; |
| let run_test_fn = format_ident!("run_test_{}", mangled_function_name(&input_fn)); |
| |
| // The identifier of the function which contains the body of the test. |
| let test_fn = &input_fn.sig.ident; |
| |
| // Implements ToTokens to generate a reference to a static-lifetime, null-terminated, C-String |
| // literal. It is represented as an array of type std::os::raw::c_char which can be either |
| // signed or unsigned depending on the platform, and it can be passed directly to C++. This |
| // differs from byte strings and CStr which work with `u8`. |
| // |
| // TODO(crbug.com/1298175): Would it make sense to write a c_str_literal!() macro that takes a |
| // Rust string literal and produces a null-terminated array of `c_char`? Then you could write |
| // `c_str_literal!(file!())` for example, or implement a `file_c_str!()` in this way. Explore |
| // using https://crates.io/crates/cstr. |
| // |
| // TODO(danakj): Write unit tests for this, and consider pulling this out into its own crate, |
| // if we don't replace it with c_str_literal!() or the "cstr" crate. |
| struct CStringLiteral<'a>(&'a str); |
| impl quote::ToTokens for CStringLiteral<'_> { |
| fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) { |
| let mut c_chars = self.0.chars().map(|c| c as std::os::raw::c_char).collect::<Vec<_>>(); |
| c_chars.push(0); |
| // Verify there's no embedded nulls as that would be invalid if the literal were put in |
| // a std::ffi::CString. |
| assert_eq!(c_chars.iter().filter(|x| **x == 0).count(), 1); |
| let comment = format!("\"{}\" as [c_char]", self.0); |
| tokens.extend(quote! { |
| { |
| #[doc=#comment] |
| &[#(#c_chars as std::os::raw::c_char),*] |
| } |
| }); |
| } |
| } |
| |
| // C-compatible string literals, that can be inserted into the quote! macro. |
| let test_suite_name_c_bytes = CStringLiteral(&test_suite_name); |
| let test_name_c_bytes = CStringLiteral(&test_name); |
| let file_c_bytes = CStringLiteral(file!()); |
| |
| let gtest_factory_fn = match >est_test_suite_wrapper_type { |
| Some(rust_type) => { |
| // Get the Gtest factory function pointer from the the TestSuite trait. |
| quote! { <#rust_type as ::rust_gtest_interop::TestSuite>::gtest_factory_fn_ptr() } |
| } |
| None => { |
| // If the #[gtest] macros didn't specify a test suite, then we use |
| // `rust_gtest_interop::rust_gtest_default_factory() which makes a TestSuite with |
| // `testing::Test` directly. |
| quote! { ::rust_gtest_interop::__private::rust_gtest_default_factory } |
| } |
| }; |
| let test_fn_call = match >est_test_suite_wrapper_type { |
| Some(_rust_type) => { |
| // SAFETY: Our lambda casts the `suite` reference and does not move from it, and the |
| // resulting type is not Unpin. |
| quote! { |
| let p = unsafe { |
| suite.map_unchecked_mut(|suite: &mut ::rust_gtest_interop::OpaqueTestingTest| { |
| suite.as_mut() |
| }) |
| }; |
| #test_fn(p) |
| } |
| } |
| None => quote! { #test_fn() }, |
| }; |
| |
| let output = quote! { |
| mod #test_mod { |
| use super::*; |
| |
| #[::rust_gtest_interop::small_ctor::ctor] |
| unsafe fn register_test() { |
| let r = ::rust_gtest_interop::__private::TestRegistration { |
| func: #run_test_fn, |
| test_suite_name: #test_suite_name_c_bytes, |
| test_name: #test_name_c_bytes, |
| file: #file_c_bytes, |
| line: line!(), |
| factory: #gtest_factory_fn, |
| }; |
| ::rust_gtest_interop::__private::register_test(r); |
| } |
| |
| // The function is extern "C" so `register_test()` can pass this fn as a pointer to C++ |
| // where it's registered with gtest. |
| // |
| // TODO(crbug.com/1296284): Removing #[no_mangle] makes rustc drop the symbol for the |
| // test function in the generated rlib which produces linker errors. If we resolve the |
| // linked bug and emit real object files from rustc for linking, then all the required |
| // symbols are present and `#[no_mangle]` should go away along with the custom-mangling |
| // of `run_test_fn`. We can not use `pub` to resolve this unfortunately. When `#[used]` |
| // is fixed in https://github.com/rust-lang/rust/issues/47384, this may also be |
| // resolved as well. |
| #[no_mangle] |
| extern "C" fn #run_test_fn( |
| suite: std::pin::Pin<&mut ::rust_gtest_interop::OpaqueTestingTest> |
| ) { |
| let catch_result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { |
| #test_fn_call |
| })); |
| use ::rust_gtest_interop::TestResult; |
| let err_message: Option<String> = match catch_result { |
| Ok(fn_result) => TestResult::into_error_message(fn_result), |
| Err(_) => Some("Test panicked".to_string()), |
| }; |
| if let Some(m) = err_message.as_ref() { |
| ::rust_gtest_interop::__private::add_failure_at(file!(), line!(), &m); |
| } |
| } |
| |
| #input_fn |
| } |
| }; |
| output.into() |
| } |
| |
| /// The `#[extern_test_suite()]` macro is used to implement the unsafe `TestSuite` trait. |
| /// |
| /// The `TestSuite` trait is used to mark a Rust type as being a wrapper of a C++ subclass of |
| /// `testing::Test`. This makes it valid to cast from a `*mut testing::Test` to a pointer of the |
| /// marked Rust type. |
| /// |
| /// It also marks a promise that on the C++, there exists an instantiation of the |
| /// RUST_GTEST_TEST_SUITE_FACTORY() macro for the C++ subclass type which will be linked with the |
| /// Rust crate. |
| /// |
| /// The macro takes a single parameter which is the fully specified C++ typename of the C++ subclass |
| /// for which the implementing Rust type is a wrapper. It expects the body of the trait |
| /// implementation to be empty, as it will fill in the required implementation. |
| /// |
| /// # Example |
| /// If in C++ we have: |
| /// ```cpp |
| /// class GoatTestSuite : public testing::Test {} |
| /// RUST_GTEST_TEST_SUITE_FACTORY(GoatTestSuite); |
| /// ``` |
| /// |
| /// And in Rust we have a `ffi::GoatTestSuite` type generated to wrap the C++ type. The the type can |
| /// be marked as a valid TestSuite with the `#[extern_test_suite]` macro: |
| /// ```rs |
| /// #[extern_test_suite("GoatTestSuite")] |
| /// unsafe impl rust_gtest_interop::TestSuite for ffi::GoatTestSuite {} |
| /// ``` |
| /// |
| /// # Internals |
| /// The #[cpp_prefix("STRING_")] attribute can follow `#[extern_test_suite()]` to control the |
| /// path to the C++ Gtest factory function. This is used for connecting to different C++ macros |
| /// than the usual RUST_GTEST_TEST_SUITE_FACTORY(). |
| #[proc_macro_attribute] |
| pub fn extern_test_suite( |
| arg_stream: proc_macro::TokenStream, |
| input: proc_macro::TokenStream, |
| ) -> proc_macro::TokenStream { |
| let args = syn::parse_macro_input!(arg_stream as syn::AttributeArgs); |
| |
| // TODO(b/229791967): With CXX it is not possible to get the C++ typename and path from the Rust |
| // wrapper type, so we require specifying it by hand in the macro. It would be nice to remove |
| // this opportunity for mistakes. |
| let cpp_type = match if args.len() == 1 { Some(&args[0]) } else { None } { |
| Some(syn::NestedMeta::Lit(syn::Lit::Str(lit_str))) => { |
| // TODO(danakj): This code drops the C++ namespaces, because we can't produce a mangled |
| // name and can't generate bindings involving fn pointers, so we require the C++ |
| // function to be `extern "C"` which means it has no namespace. Eventually we should |
| // drop the `extern "C"` on the C++ side and use the full path here. |
| let string = lit_str.value(); |
| let class_name = string.split("::").last(); |
| match class_name { |
| Some(name) => format_ident!("{}", name).into_token_stream(), |
| None => { |
| return quote_spanned! {lit_str.span() => compile_error!( |
| "invalid C++ class name" |
| )} |
| .into(); |
| } |
| } |
| } |
| _ => { |
| return quote! {compiler_error!( |
| "expected C++ type as argument to extern_test_suite" |
| )} |
| .into(); |
| } |
| }; |
| |
| /// Parses `#[cpp_prefix("PREFIX_STRING_")]` and returns `"PREFIX_STRING_"`. |
| fn parse_cpp_prefix(attr: &syn::Attribute) -> Result<String, TokenStream> { |
| let parsed = match attr.parse_meta() { |
| Ok(syn::Meta::List(list)) if list.nested.len() == 1 => match &list.nested[0] { |
| syn::NestedMeta::Lit(syn::Lit::Str(lit_str)) => Ok(lit_str.value()), |
| x => Err(x.span()), |
| }, |
| Ok(x) => Err(x.span()), |
| Err(x) => Err(x.span()), |
| }; |
| parsed.map_err(|span| { |
| quote_spanned! { span => |
| compile_error!( |
| "invalid syntax for extern_test_suite macro, \ |
| expected `#[cpp_prefix("PREFIX_STRING_")]`"); |
| } |
| }) |
| } |
| |
| let mut trait_impl = syn::parse_macro_input!(input as syn::ItemImpl); |
| if !trait_impl.items.is_empty() { |
| return quote_spanned! {trait_impl.items[0].span() => compile_error!( |
| "expected empty trait impl" |
| )} |
| .into(); |
| } |
| |
| let mut cpp_prefix = RUST_GTEST_FACTORY_PREFIX.to_owned(); |
| |
| // Look through other attributes on `trait_impl`, parse the ones related to Gtests, and put |
| // the rest back into `attrs`. |
| trait_impl.attrs = { |
| let mut keep = Vec::new(); |
| for attr in std::mem::take(&mut trait_impl.attrs) { |
| if attr.path.is_ident("cpp_prefix") { |
| cpp_prefix = match parse_cpp_prefix(&attr) { |
| Ok(tokens) => tokens, |
| Err(error_tokens) => return error_tokens.into(), |
| }; |
| } else { |
| keep.push(attr) |
| } |
| } |
| keep |
| }; |
| |
| // No longer mut. |
| let trait_impl = trait_impl; |
| let cpp_prefix = cpp_prefix; |
| |
| let trait_name = match &trait_impl.trait_ { |
| Some((_, path, _)) => path, |
| None => { |
| return quote! {compile_error!( |
| "expected impl rust_gtest_interop::TestSuite trait" |
| )} |
| .into(); |
| } |
| }; |
| let rust_type = match &*trait_impl.self_ty { |
| syn::Type::Path(type_path) => type_path, |
| _ => { |
| return quote_spanned! {trait_impl.self_ty.span() => compile_error!( |
| "expected type that wraps C++ subclass of `testing::Test`" |
| )} |
| .into(); |
| } |
| }; |
| |
| // TODO(danakj): We should generate a C++ mangled name here, then we don't require |
| // the function to be `extern "C"` (or have the author write the mangled name |
| // themselves). |
| let cpp_fn_name = format_ident!("{}{}", cpp_prefix, cpp_type.into_token_stream().to_string()); |
| |
| let output = quote! { |
| unsafe impl #trait_name for #rust_type { |
| fn gtest_factory_fn_ptr() -> rust_gtest_interop::GtestFactoryFunction { |
| extern "C" { |
| fn #cpp_fn_name( |
| f: extern "C" fn( |
| test_body: ::std::pin::Pin<&mut ::rust_gtest_interop::OpaqueTestingTest> |
| ) |
| ) -> ::std::pin::Pin<&'static mut ::rust_gtest_interop::OpaqueTestingTest>; |
| } |
| #cpp_fn_name |
| } |
| } |
| }; |
| output.into() |
| } |
