Namespace for custom commands

[brettz9]

Current behavior:

1. Add custom commands and use them.
2. Then:
   1. Be concerned that the name might conflict with a future cypress command name OR
   2. Become unsure whether your command (or that created by another) is built-in (and documented on the Cypress site) or if it is one of your own

Desired behavior:

1. See from the command name, that a custom command is being used, e.g., cy.custom.myCommand()

Test code to reproduce

N/A

Versions

Cypress 4.0.2, Mac 10.15.2, Firefox 74.0b7

[jprealini]

@jennifer-shehane I am facing a scenario similar to the one described by @brettz9
Are there any plans to support having this sort of "sub namespaces" for custom commands?
Thanks!

[IdoMor]

Hey
Any update on this one? Can we predict when this becomes available?

[AlexisLeite]

It could be a great feature to allow namespaces to custom commands!

[lmiller1990]

How would this work for long chains? Let's say I have a custom namespace with a myCustomGet:

cy.get('button').click().custom.myCustomGet().custom.myCustomGet()

This seems quite verbose and cumbersome. Is this the desired syntax, and in line with the request?

Be concerned that the name might conflict with a future cypress command name OR

This seems unlikely, the product is quite mature and we don't often add new commands at this point.

Become unsure whether your command (or that created by another) is built-in (and documented on the Cypress site) or if it is one of your own

This seems like a more compelling argument. I think it's easy to find out something is built in (just look at the docs). A short term solution might just be to have a convention, eg:

const custom = {
  get: ...,
  login: ...
}

Cypress.Commands.add("customGet", custom.get)
Cypress.Commands.add("customLogin", custom.login)

The usage would be:

// proposed w/ namespaces
cy.custom.get('button').custom.login()

// without namespaces, using convention
cy.customGet('button').customLogin()

I could be misunderstanding how the namespaced commands would be used. Maybe someone can share their desired API?

[brettz9]

It is not absolutely trivial to have to look something up in the docs, though Cypress' TypeScript support can help with this. I guess enforcing a custom or custom_ convention may do just as well (outside of cases where others haven't bothered to use the convention).

I'm ok with the issue being closed.

[lmiller1990]

Thanks for the feedback. While it would be great to iterate on this feature request, settle on an API and push forward with implementation, I think given the other higher priority feature requests, and the complexity here, it is unlikely we will get to this in a reasonable time frame. I don't want to set an unrealistic expectation that we will work on this soon, only to not make meaningful progress for months.

Maybe we can revisit this in the future - the main blocker I see with this feature is the API design. If anyone has a great proposal, happy to re-open and discuss further. If anyone wants to take a stab at this, make sure to consider these comments and edge cases.

It is not absolutely trivial to have to look something up in the docs

We should make docs trivial to use - everything about the API is here. If you have some ideas to improve docs, that's something we can do much more easily, since it doesn't require the same level of thought and design a new core API does. Happy to discuss improvements to discoverability in the docs repo - if you've got ideas, please open an issue and tag me and @elylucas and we can work on it.

[brettz9]

FWIW, I didn't mean that the docs weren't excellent. I was just saying that it can be distracting to have to leave one's code to look something up (even if you have a browser shortcut set for the Cypress site like I do to make searching even faster). But indeed, naming conventions and TypeScript do help avoid the need to leave the code to consult the docs.

[andreaslarssen]

This would be nice. Not only to separate custom commands from Cy commands, but also to namespace your own commands. Can we reopen?

[pbassut]

If this can't be supported by cypress natively, could someone provide a way to namespace commands?
I tried this and it didn't work perhaps for my limited understand of cypress:

Cypress.Commands.add('modal', () => {
  return cy.get('.modal').then((modalContext) => {
    const actions = {
      button: (label) => {
        const buttonSelector = `button:contains('${label}')`;
        return {
          click: () => modalContext.find(buttonSelector).click(),
        };
      },
    };
    return cy.wrap(actions);
  });
});

The idea was to have an api like

cy.modal().button('Label').click()

This is not cumbersome at all IMO.

Again, this doesn't need to be supported natively by Cypress. If the cypress team can come up with a way to do it I would be happy as well.