Docs for running with a specified node-version doesn't show how to change node version

laurie-wrisk commented 4 months ago

The docs here: https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-node-version, says this is the way to change the node version for the orb:

version: '2.1'
orbs:
  cypress: cypress-io/cypress@3
workflows: null

But node version isn't specified anywhere here

MikeMcC399 commented 3 months ago

@laurie-wrisk

The contents of https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-node-version (which you posted above) differ from https://github.com/cypress-io/circleci-orb/blob/master/src/examples/node-version.yml which contains:

description: >
  Run Cypress tests using the cypress/default executor with a specified node version.
usage:
  version: 2.1
  orbs:
    cypress: cypress-io/cypress@3
jobs:
  run-cypress-in-specified-node-version:
    executor:
      name: cypress/default
      node-version: "20.6"
    steps:
      - cypress/install:
          package-manager: "yarn"
      - cypress/run-tests:
          start-command: "npm run start:dev"
          cypress-command: "npx cypress run"
workflows:
  use-my-orb:
    jobs:
      - run-cypress-in-specified-node-version:
          name: Run Cypress in Node 20

I guess the two different text portions should be aligned.

It seems strange to define yarn as package-manager and then run a script with npm instead of yarn, but that doesn't hurt the node-version selection.

jennifer-shehane commented 2 months ago

Yah I'm not sure what's happened with the generated docs on the orb website. There's some usages of node-version in the repo itself: https://github.com/search?q=repo%3Acypress-io%2Fcircleci-orb%20node-version&type=code

I have no idea why that node-version file has mixed package managers either. Probably just an oversight when we last rewrote the orb.

MikeMcC399 commented 2 months ago

@jennifer-shehane

Are the docs supposed to be published automatically or is that a manual job to update them? The node-version search doesn't really bring any additional enlightenment on top of reading the full https://github.com/cypress-io/circleci-orb/blob/master/src/examples/node-version.yml.

I did at least manage to apply this to https://github.com/cypress-io/cypress-example-kitchensink/pull/859 to resolve the issue by converting from cypress/run to cypress/run-tests.

command cypress/run-tests

To resolve this issue (#468), the example text from

https://github.com/cypress-io/circleci-orb/blob/master/src/examples/node-version.yml

dealing with how to set node-version together with the command cypress/run-tests needs to be corrected and then published to

https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-node-version

job cypress/run

If there is an example for use together with the job cypress/run, then that should be added. If it is not possible to select a different Node.js version for use with the job cypress/run, then that should be explicitly stated in the documentation.

jennifer-shehane commented 1 month ago

@MikeMcC399 I feel like the actual orb doc updates if you release a new version. I don't recall ever updating the docs independently so I'm not sure if that's possible. Seems like it should be possible though.

MikeMcC399 commented 1 month ago

@jennifer-shehane

I feel like the actual orb doc updates if you release a new version. I don't recall ever updating the docs independently so I'm not sure if that's possible. Seems like it should be possible though.

I can't be of much assistance here as this part of interacting with CircleCI is only practical with Cypress.io access privileges. I have to leave it to your team to sort out. If things aren't working the way they should, then you may need to involve CircleCI support.

MikeMcC399 commented 1 week ago

The new example https://github.com/cypress-io/circleci-orb/blob/master/src/examples/node-version.yml from PR https://github.com/cypress-io/circleci-orb/pull/484 hasn't been published to https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-node-version. Nothing has changed and this issue is still unresolved.

description: >
  Run Cypress tests using the cypress/default executor with a specified node version.
usage:
  version: 2.1
  orbs:
    cypress: cypress-io/cypress@3
jobs:
  run-cypress-in-specified-node-version:
    executor:
      name: cypress/default
      node-version: "20.6"
    steps:
      - cypress/install:
          package-manager: "npm"
      - cypress/run-tests:
          start-command: "npm run start:dev"
          cypress-command: "npx cypress run"
workflows:
  use-my-orb:
    jobs:
      - run-cypress-in-specified-node-version:
          name: Run Cypress in Node 20

jennifer-shehane commented 1 week ago

Ah, pretty annoying. I feel like this might have happened before. 🤔

MikeMcC399 commented 1 week ago

@jennifer-shehane

Ah, pretty annoying. I feel like this might have happened before. 🤔

Yes, it has happened before.

The publish log works silently giving no helpful details:

Preparing to publish your orb.
Production release detected!
Production version: 3.4.0

Once an orb is created it cannot be deleted. Orbs are semver compliant, and each published version is immutable. Publicly released orbs are potential dependencies for other projects.
Therefore, allowing orb deletion would make users susceptible to unexpected loss of functionality.
Orb `cypress-io/cypress@3.4.0` was published.
Please note that this is an open orb and is world-readable.

********************************************************************************
Your orb has been published to the CircleCI Orb Registry.
You can view your published orb on the CircleCI Orb Registry at the following link: 
https://circleci.com/developer/orbs/orb/cypress-io/cypress?version=3.4.0

deiga commented 1 week ago

I think it might be an indentation problem, drafting a PR

MikeMcC399 commented 1 week ago

@deiga

I think it might be an indentation problem, drafting a PR

It's good to correct the indentation in PR #487. I'm unsure if this is the only issue however since the edge example is also not getting published (see https://github.com/cypress-io/circleci-orb/issues/482).

deiga commented 1 week ago

@deiga

I think it might be an indentation problem, drafting a PR

It's good to correct the indentation in PR #487. I'm unsure if this is the only issue however since the edge example is also not getting published (see https://github.com/cypress-io/circleci-orb/issues/482).

@MikeMcC399 I'm not sure it's the same issue. Looking at it, it seems that the example is published correctly, but the published example is not a working one

MikeMcC399 commented 1 week ago

@deiga

I'm not sure it's the same issue. Looking at it, it seems that the example is published correctly, but the published example is not a working one

I don't want to get these two issues mixed up, so I added screenshots to https://github.com/cypress-io/circleci-orb/issues/482#issuecomment-2377143023 to show that the source code and published code are different.

MikeMcC399 commented 3 days ago

@jennifer-shehane

If you want to cut a new orb release the node documentation has a good chance of being correctly published now:

Preview on https://circleci.com/developer/orbs/orb/cypress-io/cypress?version=dev:b3455e432dad1a6db0f19889495ebcf62577fa3d#usage-node-version shows:

cypress-io / circleci-orb

Docs for running with a specified node-version doesn't show how to change node version #468

command cypress/run-tests

job cypress/run