context.nest_context("") won't get the context set up about testslide

[fornellas]

I believe what you need is merge_context, and not nest_context: https://testslide.readthedocs.io/en/1.4.2/testslide_dsl/shared_contexts/index.html#sharing-contexts.

The docs can certainly be improved, but the gist is:

• merge_context, puts whatever is defined in the shared context, inside the context where it is being merged, including any hooks (before, after) and examples.
• nest_context, creates a new sub context, under the context where it is being nested, with the contents of the shared context.

Generally speaking:

• You merge contexts when you want common hooks to be used elsewhere (and perhaps also examples).
• You nest contexts when the same set of examples makes sense in different scenarios.

Makes sense?

[xush6528]

I see. So nest context is not really a shared "context" but essentially a set of shared "hooks" + "examples". It can't host more examples, but it lives like a guest in other host contexts..
Then it's so confusing to name it as context, as from the API design, I feel a context should always be an environment that can host examples.

[fornellas]

I agree, this is far from obvious. RSpec (which heavily inspired the DSL) calls them shared examples (and include_examples) and shared contexts (and include_context). How about using the same naming scheme?

[xush6528]

It's better anyway.

I think "merge_context" is good and easy to understand.

"nest_context" would be better to be called "include_context".
"Include" sounds more like reusing a of piece of code, indicating what it does clearly.

[xush6528]

There is the confusion to expect "merge_context" and "nest_context" behave similarly, because they are both derived from "shared_context".

I hope the concept of "shared_context" could be taken down (as #13 suggested), so users will not have this assumption.

[xush6528]

I have a new idea about this issue.

I realized that the problem is actually that when I want to re-use a context, what parts of the context I want to bring in.

A context has two parts basically,

• one is for setting up some constants, helper function and mocks,
• the other part is the examples enclosed in the context.

Instead of having two decorator "merge_context" and "nest_context" that users have to read doc to understand their differences.

I think it's better to just provide a single decorator but with arguments allowing users to choose what to bring in, the setups or the examples or all.

[fornellas]

That makes sense. But there's another aspect of that as well. Sometimes you actually want to merge another context hooks / examples at the same level, and other times, you want to create another sub_context, and put it there. If we don't provide that, the latter case would require defining a sub_context, and then merging it there. Having nest_context is a convenience.

Summarizing things that were said:

• Contexts are a gorup of hooks and/or examples.
• They can be "real", meaning its examples will be executed, or "virtual", that examples are not executed.
• "virtual" contexts are useful for importing its hooks and/or examples into another context (code sharing).
  • Potentially, this can happen in a new sub_context for convenience.

(I said "real" and "virtual" here to avoid biasing towards names)

Question now is: what naming / interface would make all of this clear?

Looking back at RSpec's naming scheme, shared_examples can actually... contain hooks as well, which can be misleading...

From your suggestion, I suppose you meant something like this:

context.include_shared_context(
  nested=True/False,
  examples=True/False,
  hooks=True/False,
)

Which seems a bit cumbersome... not to mention, that if you pull examples from a context, you must pull the hooks as well... And if you pull just hooks, it can be a bit confusing...

I feel like we're prematurely going after problems that are not necessarily here yet.

My suggestion to close this issue is:

• Keep the current model, as it seems to cover all use cases.
• Find more appropriate names for the DSL methods.
• Update the docs.

Fair?

[fornellas]

I updated the docs to make things clearer. I'm closing this issue now, as it seems to be mostly a documentation issue than anything else. Feel free to ping back if you find a working solution I haven't seen.

Thanks for the report!