Proposal: consider renaming pluginsFile

[brian-mann]

Overview

When we originally came up with the concept of plugins - it was primarily designed for distributing and publishing in 3rd party code with the idea that you'd primarily use things like webpack for spec preprocessing.

I like keeping the namespace of plugins but referring to it as a concept of installing 3rd party code, as opposed to also referring to it as plugins when you go to consume those plugins.

Why this is a problem

I'm a firm believer that you can generally "feel" how well a system is designed the moment you try to explain it to people. When writing the documentation for how plugins work, it is/was painfully obvious that there were some real disconnects. Here are some examples...

1. Plugins top level navigation

There is a top level navigation in the Documentation for Plugins.

The scope of this page is fine - it lists out the available plugins published by us or other authors. The problem appears though because we're adding notes about potentially routing you to a different place in the docs. We say: "Looking for API docs?" Let's investigate why would we need to do that...

2. Plugins Guide

Because you often want to utilize the plugins interface to customize and tap into its events, we needed to write an entire guide that summarizes how this works - without getting into any of the API specifics for each event. The problem here is that it acts as both as: "consuming 3rd party plugins" and also "writing your own customization".

There in lies the entire problem, "Looking for API Docs" is about "writing plugins", whereas the "Plugins List" is about consuming plugins. The problem with "writing plugins" is that it confuses and couples the idea of distribution with your own local customization. The vast majority of the plugins events aren't useful to distribute as a separate package, they are primarily useful for your own project.

This guide also effectively lays out the concept of "what plugins do". It says: "Plugins allow you to tap into the node process, outside of the browser process". That's a great feature, but it's confusing because tapping into the node process is useful irrespective of whether or not you're using a 3rd party plugin. In fact, it's a fundamental thing you should be using in virtually all projects (especially with the new cy.task API).

PS. are plugins really tooling? It doesn't really make sense in this category because this document is all about laying out the use case for tapping into the node process. Whereas other frameworks like karma or babel use plugins as configuration in .json files - instead of Cypress taking its normal magic approach, it actually makes consuming plugins just like any other npm package with zero magic whatsoever. You just write .js code and require the plugin. This means we really don't need a special guide for consuming plugins because well... there's no need to.

3. Plugin event specific API docs

We also have a very hard to find and hidden section in the API docs that is the meat and potatoes of actually writing a plugin based on the event.

The problem with these docs is the confusion around what a plugin is. The majority of the events we yield would be unique to a single project and not part of any kind of plugin system.

4. Plugins may not actually be used or written for the pluginsFile

Another problem with the whole concept of the pluginsFile is that plugins themselves may not actually be used in the pluginsFile.

There are many use cases of plugins being custom commands that would only be registered in the browser context not the node context. You may also want to use something outside of Cypress completely via the use of the module API.

5. supportFile

The addition of the supportFile is also confusing. The supportFile is special in that its processed and served just like your spec files - but done so independently of the specs and always served before the specs.

But that's not really that clear. Without more context, why wouldn't the supportFile also be used for "support" your spec via the use of cy.task or other plugin events?

Proposal

• Keep the top namespace of "Plugins" in the documentation. Remove verbiage around "Looking for API docs?" once we cleanup this whole mess because it will no longer be needed.
• Refer to Plugins as a concept of: "Publishing and consuming 3rd party packages that change or modify Cypress behavior outside of the core functionality." Let's not couple the idea of Packages to anything specific to the pluginsFile because plugins themselves could be useful in spec files (like any other NPM package).
• Remove the whole idea of pluginsFile - don't ever use the word plugin when referring to how it works today.
• Instead, we should piggyback on the idea of the supportFile but bisect its responsibilities into what the true differences are between the current idea of plugins and support. It's all about the context that they're evaluated in. One is packaged and evaluated in the browser - the other is evaluated in node. That's it! That's the single point of differentiation.

We now go from this...

> plugins
  > index.js
> support
  > index.js
  > commands.js

To this...

> support
  - browser.js
  - commands.js
  - node.js

Or this...?

> cypress
  > specs
  - browser-support.js
  - node-hooks.js

  - spec-support.js
  - node-support.js

  - browser.js
  - node.js

The support/browser.js will be the main entrypoint for the support file that is served prior to each spec file.

It's as if we're doing this in each spec file..

// cypress/integration/app.spec.js
require('../support/browser')

it('is true', () => { })

The functionality of the existing supportFile stays the same - it just gets renamed to support/browser.js

For the existing behavior of pluginsFile it also stays the same - it just gets renamed to support/node.js

We then update all of the docs to clarify on the differences - one file is processed and sent to the browser - the other is utilized by node to tap into the event system.

With that said, I'm not 100% sold on the support/browser.js vs support/node.js but the idea is to try to consolidate these and make it clear that the separate of differences is about the context they run in.

We could even alternatively have something like...

- index.js
> support
  - index.js
  - commands.js

With the index.js file being what pluginsFile is today. That way supportFile isn't necessarily modified, but I think we miss a good opportunity to make it clear what the two differences are. Someone first looking at index.js would probably be pretty confused as in thinking:

• "why is this here?"
• "what is this evaluating?"
• "when does this run?"

Concerns

By removing "Plugin Events" we lose the ability to refer to that as specifically.

For instance there is already a "Catalog of Events API" that refers to events that Cypress and cy emit specifically for the browser.

To accommodate this, I think it requires us also bifurcating the Events API into:

Events
  - Catalog of Browser Events
  - Catalog of Node Events

We might even be able to get away with documenting all of the "Plugin Events" into a single document - which would make it much easier to find and keep things less repetitive and fractured in the docs.

When we rename / move around the the Tooling - Plugins guide we could instead refer to it as Tooling - Extending Cypress or References - Customizing Cypress. I'll have to look at other frameworks to see how they refer to this. The idea is is that you can write code to change / customize Cypress's behavior (or configuration) using node.

[brian-mann]

/cc @jennifer-shehane @amirrustam @chrisbreiding @bahmutov

[bahmutov]

Trying to explain is a nice metric. Browser vs node files in support are nice too. Plugins and events are work in progress. Maybe makes sense to talk about browser and node events? Same with plugins?

…

Sent from my iPhone

On Jun 2, 2018, at 23:16, Brian Mann ***@***.***> wrote: /cc @jennifer-shehane @amirrustam @chrisbreiding @bahmutov — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[brian-mann]

We could call them:

• Browser Events
• Extension Events

I was / am a little worried "Extension" sounds like "Browser Extension" but its really the hooks into the Cypress node process in order to customize or extend Cypress's built in behavior...

[jennifer-shehane]

The scope of this page is fine - it lists out the available plugins published by us or other authors.

I actually do not believe the scope of the main Plugins doc is accurate. It's expanded to be a more general all-purpose 'add-ons to use with Cypress' more so that 'plugins' specifically. You can see this in our addition of sections for 'development tools', 'custom commands', and now even 'reporting'.

---

I agree with most everything else stated, but do not really like the suggested support/browser.js vs support/node.js for a couple of reasons:

1. Users do not like us being prescriptive about how they should structure their files.
2. Having 2 sibling files that are processed completely differently purely on the name/location of the file is just....not obvious. Everyone is already confused about how the processing of our files occur. We need to give them more visibility/control over this process.

I would prefer allowing them to hook into events and define custom commands from wherever they want - obviously, we have to restrict it to some directory - we're not going to grep their entire project for defined events and custom commands. The support dir would be fine.

[brian-mann]

Some other ideas to call the pluginsFile...

• hooks.js <-- something that acts as "Background Hooks" or "Node Hooks"
• background.js <-- we could describe it as "Accessing the Node background process" to do whatever you'd like in node. This pairs well with task in the sense that its being executed in the background. We could then describe the events as: "Browser Events" and "Background Events".

I really liked hooks.js and marinated on it for awhile, but now I think background.js is superior.

[amirrustam]

background.js gives more explicit context, so it's superior in that regard. I tried to come up with something different than background, but nothing really felt right.

[chrisbreiding]

I like background.js too.

[chrisbreiding]

The code for this is complete, but not yet released. It will be released in 4.0.

[jennifer-shehane]

The work for this was never released.

Related issue #2285

[emilyrohrbough]

Changes coming in 10.0 will replaces pluginFile with a nodeEvents key. This is no longer applicable.