Misleading documentation of Truffle configuration

[barakman]

Issue

The example of how to configure Truffle (in truffle-config.js) is misleading.

More specifically, the network name used everywhere is development (see here).

But the default network name for commands such as truffle test is production.

Subsequently, anyone who follows your configuration example is doomed to get a Could not connect to your Ethereum client error. In fact, even specifying the network name explicitly, for example, truffle test --network development doesn't seem to resolve that. So in short, a production network must be used in the configuration file.

I believe that this it is pretty clearly the case in truffle's source code.

Thanks

UPDATE:

TBH, even running truffle test --network production when the network name in the configuration file IS production, results with a Could not connect to your Ethereum client error.

Moreover, even declaring a development network in addition to the production network (and not instead of it), results with a Could not connect to your Ethereum client error.

So there must be something fundamentally wrong with how you handle of this specific part in the configuration file (or some restriction which is not stated in the official documentation).

[eggplantzzz]

Hey @barakman! Actually the default network name used by Truffle is "development". The production property you mentioned above is not actually the network name. That is actually used to determine some logic during migrations (see https://github.com/trufflesuite/truffle/blob/develop/packages/core/lib/commands/migrate.js#L142-L144). If you do not specify a specific network when running truffle test it will use the name "test". If you have these defined in the networks section of your truffle-config.js it will use them, otherwise it will just use some defaults set in Truffle.

There is probably something else going on for you here. Can you give me very specific steps to take to try and reproduce your error? If you do I'll see if I can reproduce and figure out what is going wrong.

[barakman]

@eggplantzzz:
Sure thing, I've also assumed your suggestion, but I haven't been able to ascertain that.

There you go:

1. Clone [email protected]:barakman/solidity-math-utils.git
2. Edit file truffle-config.js and rename production to development
3. Run yarn install
4. Run yarn test

The printout on my env is:

yarn run v1.22.10
$ truffle test --bail
> Something went wrong while attempting to connect to the network. Check your network configuration.

Could not connect to your Ethereum client with the following parameters:
    - host       > 127.0.0.1
    - port       > 8545
    - network_id > *
Please check that your Ethereum client:
    - is running
    - is accepting RPC connections (i.e., "--rpc" option is used in geth)
    - is accessible over the network
    - is properly configured in your Truffle configuration file (truffle-config.js)

Truffle v5.3.5 (core: 5.3.5)
Node v12.20.0
error Command failed with exit code 1.

Thank you very much :)

[eggplantzzz]

Ok so I'm actually partly wrong. Truffle looks to see if you have a "development" network defined when you run truffle test. If there is one, it uses that (https://github.com/trufflesuite/truffle/blob/develop/packages/core/lib/commands/test/index.js#L130-L136). If you don't have an ethereum client running where it specifies, then you will get the error you mentioned. If you get rid of the "development" network, Truffle will spin up it's own instance of Ganache under the hood and use that.

So this doesn't work exactly like you thought at first but is there some suggestion you could make that you think would make things easier?

[barakman]

@eggplantzzz: Thanks.

So you're saying that:

• If I declare a development network in my Truffle configuration file, then I must start a Ganache process myself before executing truffle test
• If I don't declare a development network in my Truffle configuration file, then a Ganache process will be initiated internally by truffle test as I execute it

Well, first of all, I don't quite understand the logical reasoning for this behavior (or let's just say - I cannot quite think of one).

Second, as the documentation suggests to declare a development network, it actually serves as a pretty bad advice to the user, who now needs to figure out how and when to start the Ganache process.

This used to be more intuitive in Truffle 4.x, where Ganache was not a part of the Truffle package, and one would need to install it separately. But once Ganache is integrated into the Truffle package, in a way, users are oblivious to it. For example, there's no longer any need to declare it in the package.json file.

Subsequently, I believe that requiring the user to start Ganache manually before truffle test is excessive.

My suggestion? Well, as I said above, I cannot think of a good reasoning for truffle test to behave differently when the network name is development.

So the best IMO would be to revoke this special-case behavior.

If you do have a good reasoning for this, and you wish to attain the documentation instructing to use a development network, then I think that the "missing Ganache process" issue can be "resolved" by adding it to the configuration itself, for example:

    networks: {
        development: {
            host: 'localhost',
            port: 8545,
            network_id: '*',
            gasPrice: 20000000000,
            gas: 9500000,
            provider: ganache.provider({
                gasLimit: 9500000,
                gasPrice: 20000000000,
                default_balance_ether: 10000000000000000000
            })
        }

So as an alternative to my previous suggestion, assuming that the above works (I haven't tried it TBH), you may want to add that to the documentation.

But again, this would require the user to be "aware" of Ganache, and as far as I understand, one of Truffle 5.x goals has been to relieve its users from dealing with Ganache to begin with.

Thank you for your help :)

[barakman]

BTW, the same behavior (Could not connect to your Ethereum client) applies if I use a network named test.

So we have at least two different network names - development and test - each of which unusable without starting Ganache manually.

[eggplantzzz]

Yes, Truffle always looks for "development". It is meant to be sort of the default configuration. And yes, if it finds it it will try to connect using that configuration. If there is no default, it starts up its own instance.

Unfortunately we can't change this behavior at the moment since it would be a breaking change. The docs are pretty accurate in that they say that Truffle will try to connect using the configuration provided.

Your configuration above will only work if you run Ganache separately. When you specify a provider like you have, you still need an instance of a network running - the provider only acts as the mechanism that communicates with the network.

Maybe the best thing to do is to put a note in the docs explaining the situation with "development" and "test" and how they are "default configurations". What do you think?

[barakman]

@eggplantzzz:

OK, I just realized that in order to get truffle test running, I don't even need to use the networks property in my configuration file, i.e., the development network is designated for more advanced usage of Truffle, when one wishes to override the default setup.

So to begin with, it kinda reduces the "overall confusion" that I had initially found within the documentation.

I still think that you may want to mention this in the documentation in some way, so that users will avoid adding that network in their configuration file (as it is probably not needed by the vast majority of them).

So to answer the question at the bottom of your message above - yes, I think that it somehow needs to be mentioned (something like - "if you wish to override the network configuration used by truffle test, then you can do it as follows...").

Thank you for your help. My initial conjecture about the network name production being required was silly. I even kinda noticed that while pointing you to the place in Truffle source code where I saw a property of the same name being used for something else, yet I still ended up mentioning it.

Anyways, glad we've sorted that out, and thanks again for your much appreciated help!!!

[eggplantzzz]

Thanks for the feedback! I know there are still a lot of ways to improve our docs, I'll make a change in the docs to note this behavior. Thanks!

[eggplantzzz]

So @barakman, a PR for this was merged here where I added some text to describe the default behavior. Thanks again!