Linking Cypress tests to cases

Each result goes to a Probara test case. A test that names its case is linked to it; a test that names none is matched by its automation key, and its case is created the first time it is reported. Link tests when their cases already exist in Probara (written by hand, or imported).

Two ways to name a case

Way	Example	When
A case id in an `it` or `describe`	`it('SHOP-12 pays with a card', ...)`	The usual way; works for skipped too
`probara.id()` in the test or a hook	`probara.id('SHOP-14')`, `probara.id(['A', 'B'])`	Without touching the title

describe('Checkout', () => {
  it('SHOP-12 pays with a card', () => {
    cy.get('.pay-card').click();
  });

  describe('SHOP-13 Vouchers', () => {
    it('pays with a voucher', () => {
      cy.get('.pay-voucher').click();
    });
  });

  it('pays with a gift card', () => {
    probara.id('SHOP-14');
    cy.get('.pay-gift').click();
  });

  it('shows the total', () => {
    // No case named: matched by its key, created the first time.
    cy.get('.total').should('be.visible');
  });
});

Probara receives one result per test, each with its case, and the key it would get without the ids:

[
  {
    "caseDisplayId": "SHOP-12",
    "automationKey": "cypress/e2e/checkout.cy.js > Checkout pays with a card"
  },
  {
    "caseDisplayId": "SHOP-13",
    "automationKey": "cypress/e2e/checkout.cy.js > Checkout Vouchers pays with a voucher"
  },
  {
    "caseDisplayId": "SHOP-14",
    "automationKey": "cypress/e2e/checkout.cy.js > Checkout pays with a gift card"
  },
  { "automationKey": "cypress/e2e/checkout.cy.js > Checkout shows the total" }
]

Title ids are the ids of the reported project (and of projects) in a describe or it title. An id in a describe links every test inside it. They are removed from the key, so adding one never changes a key. An id of a project the reporter does not know, such as WEB-3 without projects: ['WEB'], stays in the title and in the key, as text.
probara.id() takes an id or a list, and links the running test; in a beforeEach, it links every test of the block. It needs the plugin and the support file. A test skipped before it runs (it.skip) never runs its body: link it with a title id instead. Run selection does not see probara.id() either: it decides before the test runs.

The ids are the case’s display id: the Project ID, a dash and the number shown in Probara (SHOP-12). An id Probara does not know is not recorded: the log names it as unmatched (troubleshooting). Several ids, in titles or in probara.id(), link the test to several cases, and the test is recorded once per case.

Automation keys

A test that names no case is matched by its automation key: the same key finds the same case on every run, and a new key creates a new case. The key is the one probara import junit gives the test on the report of Cypress’s junit reporter or of cypress-junit:

<spec path, relative to the project root> > <the full title of the test>

Part	From	Example
The spec path	Relative to `rootDir` (Cypress’s `projectRoot`), with `/` separators, while `keyIncludesFile` is on	`cypress/e2e/cart.cy.js`
The full title	The `describe` titles and the `it` title joined by single spaces, as one segment, without the case ids	`Cart Checkout pays`

describe('SHOP-12 Cart', () => {
  describe('Checkout', () => {
    it('pays by card', () => {
      cy.get('.pay').click();
    });
  });
});

cypress/e2e/cart.cy.js > Cart Checkout pays by card

What changes a key

What	Why
Renaming a spec, a `describe` or an `it`	The spec path and the titles are the key
Moving a spec	Its path is the key
Starting `cypress run` from another directory	The path is relative to Cypress’s `projectRoot`
Changing `keyIncludesFile` or `rootDir`	They decide whether the spec path is in the key, and what it is relative to

Nothing else reaches a key: not the browser (a browser parameter of the result), not the attempt, not a parameter, tag or step, not the CI build, the machine, --spec or excludeSpecPattern. Name the cases in the titles before a rename, so the tests keep them.

Traps in Cypress

Two tests with the same full title are one case. Mocha allows it('adds an item') twice in one describe, and a b › c next to a › b c has the same full title a b c. Both record into one case, and what their probara.* calls said is left out rather than given to the wrong test. Give every test its own title.
it.only leaves out what it does not run. Cypress removes the other tests from its tree before anything runs, so they are not reported at all, not even as skipped. The same holds for the specs --spec leaves out.
A failing hook is a test of its own, named "before each" hook for "…" by Cypress, and by the import. Its key is the one a JUnit report holds (hooks).
A spec Cypress cannot parse is one result named Spec failed to run (specs that cannot run).

Missing cases

A test whose key matches no case creates one, named after the test (ids removed), under suiteUlid (the project root by default), in a suite path made of the spec file and the describe blocks the test is in: cypress/e2e/cart.cy.js › Cart › Checkout. A test outside any describe sits in the spec alone. With keyIncludesFile: false, the spec leaves the suite path too. With createMissingCases: false (PROBARA_CREATE_MISSING_CASES=false) such a test records nothing and is logged as unmatched: only existing cases get results. probara.title() and probara.suite() choose the name and the suite of a created case.

The same keys as `probara import junit`

A project that sent Cypress’s JUnit XML with probara import junit can switch to the reporter and keep every case: the reporter builds the same keys and reads the same title ids.

The JUnit report	Reporter setting
Written by Cypress’s `junit` reporter or cypress-junit, default options	Nothing: `keyIncludesFile` is on
Written without the `file` attribute of its root suite	`keyIncludesFile: false`

The one visible difference is where a created case sits: the reporter puts it under the spec and its describe blocks, the import under the spec alone, since a JUnit report cannot split the describe titles back out of one title. An existing case never moves (migrating from the JUnit import).

Related: Metadata and links · Sharding and projects · Upgrading · Source: linking.md