Contributor guidelines/docs for tests (maybe other stuff too)

[acolytec3]

Coming from this question that @faustbrian asked, we should definitely take a look at our contributor documentation (such as it is) and bring it up to speed with our current way of working/coding style/etc. A good example of something we should really coalesce around is a coding style for tests. I don't know if this is written down anywhere but our style for at least as long as I've been on the team is to write tests as follows:

tape("test something", (t) => { 
   // do some tests
   t.test("write some subtests", (st) => { //some subtests })
   t.end()
})

I think there would be some value in us agreeing on this and things like it as standards we follow. Just to take this example a little bit farther as to why to do it this way is like this. In tape, we often are trying to fix one broken test deep in some test file and we have to comment out tons of lines of code and then uncomment them once we fix that specific test.

If we broke up our tests into small blocks of

tape("test something else", (t) => { ///test })

It's very easy to just put tape.only by the specific test or set of tests you want to run and tape will disregard all the others. I know this may feel like a silly thing but this is a genuinely useful example (at least for me) of where following a consistent coding style could save us untold hours down the line when we're trying to fix tests impacted by some obscure change somewhere across the monorepo.

[acolytec3]

@ethereumjs/committers thoughts?

[holgerd77]

@acolytec3 maybe don't use this specific group mention, this triggers a lot of mentions to people (currently 17 members) who are not actively contributing.

[holgerd77]

Otherwise big fan here, yes that would bring a lot of value (currently not written down anywhere)! 🙂 ❤️ We can do some first brainstorming round in the call later the day.

So we have this more or less forgotten ReadTheDocs documentation at https://ethereumjs.readthedocs.io, just to throw this in the ring, totally not sure what to do with it. Getting more and more to the point that it just might not be realistic to maintain, and we might want to reintegrate the most valuable parts in the monorepo? Not sure just a first-shot idea.

But anyhow, to the point here: test documentation/guidelines is also not written down there.

I would also see value in some agreement/guidelines on:

• How to structure tests (I lately often found value in simply do method by method)
• How to somewhat visualize/help understand this structure in the description fields?
• Generally, some how-to-use conventions on the description fields, also some style guidelines (in the forefront: should-sentences vs simple test descriptions)

Yeah, so likely nice to have written some of this down.

[holgerd77]

@acolytec3 Is this relevant for Vitest in the same way as described?

[acolytec3]

@acolytec3 Is this relevant for Vitest in the same way as described?

Sort of. With the it usage in vitest, you can say it.only and achieve the goal here. We should probably still think about working on our contributor documentation.