test_api.rs 13.2 KB
Newer Older
1
// Copyright 2018-2021 Parity Technologies (UK) Ltd.
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Operations on the off-chain testing environment.

use super::{
18
    chain_extension::ChainExtension,
19
20
21
22
23
    db::ExecContext,
    AccountError,
    EnvInstance,
    OnInstance,
};
24
25
26
27
28
pub use super::{
    db::ChainSpec,
    CallData,
    EmittedEvent,
};
29
use crate::{
30
    Environment,
31
32
33
    Result,
};
use ink_prelude::string::String;
34
use std::panic::UnwindSafe;
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

/// Pushes a contract execution context.
///
/// This is the data behind a single instance of a contract call.
///
/// # Note
///
/// Together with [`pop_execution_context`] this can be used to emulated
/// nested calls.
pub fn push_execution_context<T>(
    caller: T::AccountId,
    callee: T::AccountId,
    gas_limit: T::Balance,
    endowment: T::Balance,
    call_data: CallData,
) where
51
    T: Environment,
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance.exec_context.push(
            ExecContext::build::<T>()
                .caller(caller)
                .callee(callee)
                .gas(gas_limit)
                .transferred_value(endowment)
                .call_data(call_data)
                .finish(),
        )
    })
}

/// Pops the top contract execution context.
///
/// # Note
///
/// Together with [`push_execution_context`] this can be used to emulated
/// nested calls.
pub fn pop_execution_context() {
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance.exec_context.pop();
    })
}

/// Sets the balance of the account to the given balance.
///
/// # Note
///
/// Note that account could refer to either a user account or
/// a smart contract account.
///
/// # Errors
///
/// - If `account` does not exist.
/// - If the underlying `account` type does not match.
/// - If the underlying `new_balance` type does not match.
pub fn set_account_balance<T>(
    account_id: T::AccountId,
    new_balance: T::Balance,
) -> Result<()>
where
95
    T: Environment,
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account_mut::<T>(&account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(&account_id))
            .map_err(Into::into)
            .and_then(|account| account.set_balance::<T>(new_balance).map_err(Into::into))
    })
}

/// Returns the balance of the account.
///
/// # Note
///
/// Note that account could refer to either a user account or
/// a smart contract account. This returns the same as `env::api::balance`
/// if given the account ID of the currently executed smart contract.
///
/// # Errors
///
/// - If `account` does not exist.
/// - If the underlying `account` type does not match.
pub fn get_account_balance<T>(account_id: T::AccountId) -> Result<T::Balance>
where
121
    T: Environment,
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account::<T>(&account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(&account_id))
            .map_err(Into::into)
            .and_then(|account| account.balance::<T>().map_err(Into::into))
    })
}

/// Sets the rent allowance of the contract account to the given rent allowance.
///
/// # Errors
///
/// - If `account` does not exist.
/// - If the underlying `account` type does not match.
/// - If the underlying `new_rent_allowance` type does not match.
pub fn set_contract_rent_allowance<T>(
    account_id: T::AccountId,
    new_rent_allowance: T::Balance,
) -> Result<()>
where
145
    T: Environment,
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account_mut::<T>(&account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(&account_id))
            .map_err(Into::into)
            .and_then(|account| {
                account
                    .set_rent_allowance::<T>(new_rent_allowance)
                    .map_err(Into::into)
            })
    })
}

/// Returns the rent allowance of the contract account.
///
/// # Errors
///
/// - If `account` does not exist.
/// - If the underlying `account` type does not match.
/// - If the returned rent allowance cannot be properly decoded.
pub fn get_contract_rent_allowance<T>(account_id: T::AccountId) -> Result<T::Balance>
where
170
    T: Environment,
171
172
173
174
175
176
177
178
179
180
181
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account::<T>(&account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(&account_id))
            .map_err(Into::into)
            .and_then(|account| account.rent_allowance::<T>().map_err(Into::into))
    })
}

Hero Bird's avatar
Hero Bird committed
182
/// Registers a new chain extension.
183
pub fn register_chain_extension<E>(extension: E)
184
where
185
    E: ChainExtension + 'static,
186
187
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
188
189
190
        instance
            .chain_extension_handler
            .register(Box::new(extension));
191
192
193
194
195
196
197
    })
}

/// Set the entropy hash of the current block.
///
/// # Note
///
198
/// This allows to control what [`random`][`crate::random`] returns.
199
200
pub fn set_block_entropy<T>(entropy: T::Hash) -> Result<()>
where
201
    T: Environment,
202
203
204
205
206
207
208
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance.current_block_mut()?.set_entropy::<T>(entropy)
    })
    .map_err(Into::into)
}

209
/// Update the [`ChainSpec`](`crate::test::ChainSpec`) for the test environment
210
211
pub fn update_chain_spec<F>(f: F) -> Result<()>
where
212
    F: FnOnce(&mut ChainSpec),
213
{
214
    <EnvInstance as OnInstance>::on_instance(|instance| f(instance.chain_spec_mut()));
215
216
217
    Ok(())
}

218
219
/// Returns the contents of the past performed environmental debug messages in order.
pub fn recorded_debug_messages() -> impl Iterator<Item = String> {
220
221
222
223
224
225
226
    <EnvInstance as OnInstance>::on_instance(|instance| {
        // We return a clone of the recorded strings instead of
        // references to them since this would require the whole `on_instance`
        // API to operate on `'static` environmental instances which would
        // ultimately allow leaking those `'static` references to the outside
        // and potentially lead to terrible bugs such as iterator invalidation.
        instance
227
228
            .debug_buf
            .past_debug_messages()
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
            .map(ToOwned::to_owned)
            .collect::<Vec<_>>()
            .into_iter()
    })
}

/// Returns the recorded emitted events in order.
pub fn recorded_events() -> impl Iterator<Item = EmittedEvent> {
    <EnvInstance as OnInstance>::on_instance(|instance| {
        // We return a clone of the recorded emitted events instead of
        // references to them since this would require the whole `on_instance`
        // API to operate on `'static` environmental instances which would
        // ultimately allow leaking those `'static` references to the outside
        // and potentially lead to terrible bugs such as iterator invalidation.
        instance
            .emitted_events
            .emitted_events()
            .map(Clone::clone)
            .collect::<Vec<_>>()
            .into_iter()
    })
}

/// Advances the chain by a single block.
pub fn advance_block<T>() -> Result<()>
where
255
    T: Environment,
256
257
258
259
{
    <EnvInstance as OnInstance>::on_instance(|instance| instance.advance_block::<T>())
}

260
261
262
263
/// Set to true to disable clearing storage
///
/// # Note
///
264
/// Useful for benchmarks because it ensures the initialized storage is maintained across runs,
265
266
267
268
269
270
271
/// because lazy storage structures automatically clear their associated cells when they are dropped.
pub fn set_clear_storage_disabled(disable: bool) {
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance.clear_storage_disabled = disable
    })
}

272
273
274
/// The default accounts.
pub struct DefaultAccounts<T>
where
275
    T: Environment,
276
{
277
    /// The predefined `ALICE` account holding substantial amounts of value.
278
    pub alice: T::AccountId,
279
    /// The predefined `BOB` account holding some amounts of value.
280
    pub bob: T::AccountId,
281
    /// The predefined `CHARLIE` account holding some amounts of value.
282
    pub charlie: T::AccountId,
283
    /// The predefined `DJANGO` account holding no value.
284
    pub django: T::AccountId,
285
    /// The predefined `EVE` account holding no value.
286
    pub eve: T::AccountId,
287
    /// The predefined `FRANK` account holding no value.
288
289
290
291
292
293
294
    pub frank: T::AccountId,
}

/// Returns the default accounts for testing purposes:
/// Alice, Bob, Charlie, Django, Eve and Frank.
pub fn default_accounts<T>() -> Result<DefaultAccounts<T>>
where
295
296
    T: Environment,
    <T as Environment>::AccountId: From<[u8; 32]>,
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
{
    Ok(DefaultAccounts {
        alice: T::AccountId::from([0x01; 32]),
        bob: T::AccountId::from([0x02; 32]),
        charlie: T::AccountId::from([0x03; 32]),
        django: T::AccountId::from([0x04; 32]),
        eve: T::AccountId::from([0x05; 32]),
        frank: T::AccountId::from([0x06; 32]),
    })
}

/// Initializes the whole off-chain environment.
///
/// # Note
///
/// - Initializes the off-chain environment with default values that fit most
/// uses cases.
314
pub fn initialize_or_reset_as_default<T>() -> Result<()>
315
where
316
317
    T: Environment,
    <T as Environment>::AccountId: From<[u8; 32]>,
318
319
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
320
        instance.initialize_or_reset_as_default::<T>()
321
322
323
    })
}

324
/// Runs the given closure test function with the default configuration
325
326
327
/// for the off-chain environment.
pub fn run_test<T, F>(f: F) -> Result<()>
where
328
    T: Environment,
329
    F: FnOnce(DefaultAccounts<T>) -> Result<()>,
330
    <T as Environment>::AccountId: From<[u8; 32]>,
331
{
332
    initialize_or_reset_as_default::<T>()?;
333
334
335
336
337
338
339
    let default_accounts = default_accounts::<T>()?;
    f(default_accounts)
}

/// Returns the total number of reads and writes of the contract's storage.
pub fn get_contract_storage_rw<T>(account_id: &T::AccountId) -> Result<(usize, usize)>
where
340
    T: Environment,
341
342
343
344
345
346
347
348
349
350
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account::<T>(account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(account_id))
            .map_err(Into::into)
            .and_then(|account| account.get_storage_rw().map_err(Into::into))
    })
}
351

352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
/// Returns the amount of storage cells used by the account `account_id`.
///
/// Returns `None` if the `account_id` is non-existent.
pub fn count_used_storage_cells<T>(account_id: &T::AccountId) -> Result<usize>
where
    T: Environment,
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        instance
            .accounts
            .get_account::<T>(account_id)
            .ok_or_else(|| AccountError::no_account_for_id::<T>(account_id))
            .map_err(Into::into)
            .and_then(|account| account.count_used_storage_cells().map_err(Into::into))
    })
}

369
370
371
372
373
374
375
376
377
378
379
/// Returns the account id of the currently executing contract.
pub fn get_current_contract_account_id<T>() -> Result<T::AccountId>
where
    T: Environment,
{
    <EnvInstance as OnInstance>::on_instance(|instance| {
        let exec_context = instance.exec_context()?;
        let callee = exec_context.callee.decode()?;
        Ok(callee)
    })
}
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419

/// The result of a successful contract termination.
#[derive(scale::Encode, scale::Decode)]
pub struct ContractTerminationResult<E>
where
    E: Environment,
{
    /// The beneficiary account who received the remaining value in the contract.
    pub beneficiary: <E as Environment>::AccountId,
    /// The value which was transferred to the `beneficiary`.
    pub transferred: <E as Environment>::Balance,
}

/// Tests if a contract terminates successfully after `self.env().terminate()`
/// has been called.
///
/// # Usage
///
/// ```no_compile
/// let should_terminate = move || your_contract.fn_which_should_terminate();
/// ink_env::test::assert_contract_termination::<ink_env::DefaultEnvironment, _>(
///     should_terminate,
///     expected_beneficiary,
///     expected_value_transferred_to_beneficiary
/// );
/// ```
///
/// See `examples/contract-terminate` for a complete usage example.
pub fn assert_contract_termination<T, F>(
    should_terminate: F,
    expected_beneficiary: T::AccountId,
    expected_balance: T::Balance,
) where
    T: Environment,
    F: FnMut() + UnwindSafe,
    <T as Environment>::AccountId: core::fmt::Debug,
    <T as Environment>::Balance: core::fmt::Debug,
{
    let value_any = ::std::panic::catch_unwind(should_terminate)
        .expect_err("contract did not terminate");
420
    let encoded_input = value_any
421
        .downcast_ref::<Vec<u8>>()
422
423
        .expect("panic object can not be cast");
    let res: ContractTerminationResult<T> =
424
        scale::Decode::decode(&mut &encoded_input[..]).expect("input can not be decoded");
425
426
427
428

    assert_eq!(res.beneficiary, expected_beneficiary);
    assert_eq!(res.transferred, expected_balance);
}