ink_e2e_macro/
lib.rs

1// Copyright (C) Use Ink (UK) Ltd.
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#![doc(
16    html_logo_url = "https://use.ink/img/crate-docs/logo.png",
17    html_favicon_url = "https://use.ink/crate-docs/favicon.png"
18)]
19
20mod codegen;
21mod config;
22mod ir;
23
24use proc_macro::TokenStream;
25use proc_macro2::TokenStream as TokenStream2;
26use syn::Result;
27
28/// Defines an End-to-End test.
29///
30/// The system requirements are:
31///
32/// - A Substrate node with `pallet-revive` installed on the local system. You can e.g.
33///   use [`ink-node`](https://github.com/use-ink/ink-node)
34///   and install it on your PATH, or provide a path to an executable using the
35///   `CONTRACTS_NODE` environment variable.
36///
37/// Before the test function is invoked the contract will be built. Any errors that occur
38/// during the contract build will prevent the test function from being invoked.
39///
40/// ## Header Arguments
41///
42/// The `#[ink_e2e::test]` macro can be provided with additional arguments.
43///
44/// ### Custom Environment
45///
46/// You can specify the usage of a custom environment:
47///
48/// ```ignore
49/// #[ink_e2e::test(environment = crate::EnvironmentWithManyTopics)]
50/// ```
51///
52/// Our documentation contains [an explainer of what custom environments are](https://use.ink/basics/chain-environment-types).
53/// For a full example [see here](https://github.com/use-ink/ink-examples/tree/v5.x.x/custom-environment).
54///
55/// ### Custom Backend
56///
57/// You can switch the E2E test to use the [DRink!](https://use.ink/basics/contract-testing/drink)
58/// testing framework with this syntax:
59///
60/// ```
61/// type E2EResult<T> = std::result::Result<T, Box<dyn std::error::Error>>;
62///
63/// #[ink_e2e::test(backend(runtime_only))]
64/// async fn runtime_call_works() -> E2EResult<()> {
65///     // ...
66/// }
67/// ```
68///
69/// In this configuration the test will not run against a node that is running in the
70/// background, but against an in-process slimmed down `pallet-revive` execution
71/// environment.
72///
73/// Please see [the page on testing with DRink!](https://use.ink/basics/contract-testing/drink)
74/// in our documentation for more details.
75/// For a full example [see here](https://github.com/use-ink/ink-examples/tree/v5.x.x/e2e-runtime-only-backend).
76///
77/// # Example
78///
79/// ```
80/// # use ink::env::{
81/// #    Environment,
82/// #    DefaultEnvironment,
83/// # };
84/// # type AccountId = <DefaultEnvironment as Environment>::AccountId;
85/// #
86/// #[ink::contract]
87/// mod my_module {
88///     #[ink(storage)]
89///     pub struct MyContract {}
90///
91///     impl MyContract {
92///         #[ink(constructor)]
93///         pub fn new() -> Self {
94///             Self {}
95///         }
96///
97///         #[ink(message)]
98///         pub fn my_message(&self) {}
99///     }
100/// }
101///
102/// type E2EResult<T> = std::result::Result<T, Box<dyn std::error::Error>>;
103///
104/// #[ink_e2e::test]
105/// async fn e2e_test(mut client: ::ink_e2e::Client<C, E>) -> E2EResult<()> {
106///     // given
107///     use my_module::MyContract;
108///     let mut constructor = MyContract::new();
109///     let contract = client
110///         .instantiate("contract_transfer", &ink_e2e::bob(), &mut constructor)
111///         .submit()
112///         .await
113///         .expect("instantiate failed");
114///     let mut call_builder = contract.call_builder::<MyContract>();
115///
116///     // when
117///     let my_message = call_builder.my_message();
118///     let call_res = client
119///         .call(&ink_e2e::eve(), &my_message)
120///         .submit()
121///         .await
122///         .expect("call failed");
123///
124///     // then
125///     assert!(call_res.is_ok());
126///
127///     Ok(())
128/// }
129/// ```
130///
131/// You can also build the `Keypair` type yourself, without going through
132/// the pre-defined functions (`ink_e2e::alice()`, …):
133///
134/// ```
135/// use std::str::FromStr;
136/// let suri = ::ink_e2e::subxt_signer::SecretUri::from_str("//Alice").unwrap();
137/// let alice = ::ink_e2e::Keypair::from_uri(&suri).unwrap();
138/// ```
139#[proc_macro_attribute]
140pub fn test(attr: TokenStream, item: TokenStream) -> TokenStream {
141    generate(attr.into(), item.into()).into()
142}
143
144fn generate(attr: TokenStream2, input: TokenStream2) -> TokenStream2 {
145    match generate_or_err(attr, input) {
146        Ok(tokens) => tokens,
147        Err(err) => err.to_compile_error(),
148    }
149}
150
151fn generate_or_err(attr: TokenStream2, input: TokenStream2) -> Result<TokenStream2> {
152    let test_definition = ir::InkE2ETest::new(attr, input)?;
153    let codegen = codegen::InkE2ETest::from(test_definition);
154    Ok(codegen.generate_code())
155}
ink_e2e_macro/lib.rs

ink_e2e_macro/
lib.rs
