Update documentation to explain how Clean-room environment works

[sargue]

• [ ] I've opened a support ticket before filing this issue.

---

Issue

Tests are not isolated from each other. I reproduced it using the metacoin box tutorial, adding a new test at the end that checks again the balance. As per the "clean-room" the first account should have all 10000 tokens. It's not.

Steps to Reproduce

Starting from the freshly unboxed metacoin repeat the first test as the last one, adding this to the end of metacoin.js

  it('should still have 10000 MetaCoin in the first account as per clean room test env', async () => {
    const metaCoinInstance = await MetaCoin.deployed();
    const balance = await metaCoinInstance.getBalance.call(accounts[0]);

    assert.equal(balance.valueOf(), 10000, "10000 wasn't in the first account");
  });

Run truffle test.

Expected Behavior

All those tests should pass.

Actual Results

Compiling your contracts...
===========================
> Compiling ./contracts/ConvertLib.sol
> Compiling ./contracts/MetaCoin.sol
> Compiling ./contracts/Migrations.sol
> Compiling ./test/TestMetaCoin.sol
> Artifacts written to /tmp/test--190-ETkHgONXcoEN
> Compiled successfully using:
   - solc: 0.5.16+commit.9c3226ce.Emscripten.clang


  TestMetaCoin
    ✔ testInitialBalanceUsingDeployedContract (1036ms)
    ✔ testInitialBalanceWithNewMetaCoin (1022ms)

  Contract: MetaCoin
    ✔ should put 10000 MetaCoin in the first account
    ✔ should call a function that depends on a linked library
    ✔ should send coin correctly (1049ms)
    1) should still have 10000 MetaCoin in the first account as per clean room test env
    > No events were emitted


  5 passing (20s)
  1 failing

  1) Contract: MetaCoin
       should still have 10000 MetaCoin in the first account as per clean room test env:
     AssertionError: 10000 wasn't in the first account: expected <BN: 2706> to equal 10000
      at Context.<anonymous> (test/metacoin.js:44:12)
      at runMicrotasks (<anonymous>)
      at processTicksAndRejections (node:internal/process/task_queues:96:5)

Environment

• Operating System: Debian GNU/Linux 11 (bullseye)
• Ethereum client: N/A
• Truffle version (truffle version): Truffle v5.5.14 (core: 5.5.14) Ganache v^7.1.0 Solidity v0.5.16 (solc-js) Node v16.15.0 Web3.js v1.5.3
• node version (node --version): v16.15.0
• npm version (npm --version): 8.5.5

[cds-amal]

Hi @sargue,

A "clean room" is triggered when a new Contract test-block is encountered.

Try this test file

const MetaCoin = artifacts.require("MetaCoin");

contract('MetaCoin - Room 1', (accounts) => {
  before (async () => {
    const bal = await web3.eth.getBalance(accounts[0]);
    console.log(accounts[0], bal);
  });

  it('should put 10000 MetaCoin in the first account', async () => {
    const metaCoinInstance = await MetaCoin.deployed();
    const balance = await metaCoinInstance.getBalance.call(accounts[0]);

    assert.equal(balance.valueOf(), 10000, "10000 wasn't in the first account");
  });

  it('should call a function that depends on a linked library', async () => {
    const metaCoinInstance = await MetaCoin.deployed();
    const metaCoinBalance = (await metaCoinInstance.getBalance.call(accounts[0])).toNumber();
    const metaCoinEthBalance = (await metaCoinInstance.getBalanceInEth.call(accounts[0])).toNumber();

    assert.equal(metaCoinEthBalance, 2 * metaCoinBalance, 'Library function returned unexpected function, linkage may be broken');
  });
  it('should send coin correctly', async () => {
    const metaCoinInstance = await MetaCoin.deployed();

    // Setup 2 accounts.
    const accountOne = accounts[0];
    const accountTwo = accounts[1];

    // Get initial balances of first and second account.
    const accountOneStartingBalance = (await metaCoinInstance.getBalance.call(accountOne)).toNumber();
    const accountTwoStartingBalance = (await metaCoinInstance.getBalance.call(accountTwo)).toNumber();

    // Make transaction from first account to second.
    const amount = 10;
    await metaCoinInstance.sendCoin(accountTwo, amount, { from: accountOne });

    // Get balances of first and second account after the transactions.
    const accountOneEndingBalance = (await metaCoinInstance.getBalance.call(accountOne)).toNumber();
    const accountTwoEndingBalance = (await metaCoinInstance.getBalance.call(accountTwo)).toNumber();


    assert.equal(accountOneEndingBalance, accountOneStartingBalance - amount, "Amount wasn't correctly taken from the sender");
    assert.equal(accountTwoEndingBalance, accountTwoStartingBalance + amount, "Amount wasn't correctly sent to the receiver");
  });
});


contract('MetaCoin - Room 2', (accounts) => {
  before (async () => {
    const bal = await web3.eth.getBalance(accounts[0]);
    console.log(accounts[0], bal);
  });

  it('should still have 10000 MetaCoin in the first account as per clean room test env', async () => {
    const metaCoinInstance = await MetaCoin.deployed();
    const balance = await metaCoinInstance.getBalance.call(accounts[0]);

    assert.equal(balance.valueOf(), 10000, "10000 wasn't in the first account");
  });

});

I got the following results:

$ truffle test test/metacoin.js

Compiling your contracts...
===========================
> Compiling ./contracts/ConvertLib.sol
> Compiling ./contracts/MetaCoin.sol
> Compiling ./contracts/Migrations.sol
> Artifacts written to /tmp/test--303975-nwrJqCgyL0Jq
> Compiled successfully using:
   - solc: 0.5.16+commit.9c3226ce.Emscripten.clang


  Contract: MetaCoin - Room 1
0x627306090abaB3A6e1400e9345bC60c78a8BEf57 99998008940690133243
    ✔ should put 10000 MetaCoin in the first account
    ✔ should call a function that depends on a linked library
    ✔ should send coin correctly (1066ms)

  Contract: MetaCoin - Room 2
0x627306090abaB3A6e1400e9345bC60c78a8BEf57 99998008940690133243
    ✔ should still have 10000 MetaCoin in the first account as per clean room test env


  4 passing (1s)

[sargue]

I see, I understood it wrong. Thanks for the explanation.

[cds-amal]

I see, I understood it wrong. Thanks for the explanation.

Thanks for raising this @sargue, our documentation should explain how this works.

[AnmolSirola]

@davidmurdoch @cds-amal Can I work on this issue ?

[cds-amal]

@davidmurdoch @cds-amal Can I work on this issue ?

Sure, you can submit a PR, @AnmolSirola

[AnmolSirola]

@cds-amal Sir can you tell me where(in which file) I have to make the required changes

[cds-amal]

@cds-amal Sir can you tell me where(in which file) I have to make the required changes

The documentation lives on the trufflesuite/trufflesuite.com repo, in this file

[AnmolSirola]

@cds-amal Sir, I have a doubt regarding the pull request for this issue. The problem exists in the Truffle repo, but the file I need to modify is in the trufflesuit.com repo. Should I make a pull request for this issue in the trufflesuit.com repo after making the necessary changes there? or am I supposed to make it here ?