{"id":13091,"library":"drupal-test-session-cypress","title":"Drupal Test Session Cypress Commands","description":"This package, `drupal-test-session-cypress` (current version 1.1.66), provides Cypress commands that streamline interaction with Drupal's Test Session module. Its primary function is to extend the Cypress API with `cy.drupalSession()`, enabling testers to easily manage Drupal user sessions and state directly within their end-to-end tests. This abstraction simplifies common testing scenarios like logging in users, asserting permissions, and resetting session data, which otherwise would require complex custom commands or direct API calls to the Drupal backend. The package is typically installed as a development dependency and integrates by requiring it within Cypress's `support/index.js` (or `.ts`) file, making its commands globally available to Cypress tests. It offers a focused solution for projects leveraging Drupal and Cypress, differentiating itself by tightly coupling with the specific Drupal module. The Drupal Test Session module itself is marked as 'minimally maintained' and 'feature-complete' on Drupal.org, and this Cypress wrapper aligns with that stability.","status":"active","version":"1.1.66","language":"javascript","source_language":"en","source_url":"https://github.com/AmazeeLabs/silverback-mono","tags":["javascript","typescript"],"install":[{"cmd":"npm install drupal-test-session-cypress","lang":"bash","label":"npm"},{"cmd":"yarn add drupal-test-session-cypress","lang":"bash","label":"yarn"},{"cmd":"pnpm add drupal-test-session-cypress","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the underlying testing framework that this package extends. This is typically a devDependency.","package":"cypress","optional":false},{"reason":"This package is a client-side wrapper; the corresponding Drupal module must be installed and configured on the Drupal backend for `cy.drupalSession()` commands to function.","package":"Drupal Test Session module","optional":false}],"imports":[{"note":"This package augments the global Cypress `cy` object. It should be `require()`-d in your `cypress/support/index.js` or `cypress/support/index.ts` file for global availability. No direct named imports are typically used in test files for the commands themselves.","wrong":"import { drupalSession } from 'drupal-test-session-cypress';","symbol":"(global augmentation)","correct":"require('drupal-test-session-cypress');"},{"note":"Environment variables within Cypress tests should be accessed via `Cypress.env()` after being configured in `cypress.json` or `cypress.env.json`, not directly from `process.env` in browser contexts.","wrong":"process.env.DRUPAL_BASE_URL","symbol":"Cypress","correct":"Cypress.env('DRUPAL_BASE_URL')"}],"quickstart":{"code":"// cypress/support/index.ts or cypress/support/e2e.ts\n// Ensure this line is present to make drupalSession commands available.\nrequire('drupal-test-session-cypress');\n\n// Any other global Cypress configurations or custom commands can go here.\n\n// cypress/e2e/drupal-session.cy.ts (example test file)\n\ndescribe('Drupal Session Management with Cypress', () => {\n  // Configure DRUPAL_BASE_URL in cypress.config.ts/js or cypress.env.json\n  // e.g., set CYPRESS_DRUPAL_BASE_URL=http://your-drupal.local\n  const drupalBaseUrl = Cypress.env('DRUPAL_BASE_URL') || 'http://localhost:8888';\n\n  beforeEach(() => {\n    // It's often necessary to visit the base URL before session commands\n    // to ensure Cypress is within the correct origin for cookie and session handling.\n    cy.visit(drupalBaseUrl);\n  });\n\n  it('should allow logging in an administrator user', () => {\n    // Use cy.drupalSession to create and log in a user with the 'administrator' role.\n    // This command interacts with the Drupal Test Session module on the backend.\n    cy.drupalSession({\n      user: {\n        name: 'testadmin',\n        mail: 'testadmin@example.com',\n        roles: ['administrator'],\n      },\n      // Set kill to false to maintain the session for subsequent commands or tests.\n      kill: false,\n    }).then((userSession) => {\n      // Assertions after successful login\n      expect(userSession).to.have.property('name', 'testadmin');\n      cy.url().should('include', '/user');\n      cy.get('.toolbar-icon-user').should('be.visible'); // Example for Drupal admin toolbar\n      cy.contains('Hello testadmin').should('be.visible'); // Check for a greeting (adjust selector as needed)\n    });\n  });\n\n  it('should reset the Drupal session, effectively logging out', () => {\n    // First, log in a user to establish a session.\n    cy.drupalSession({\n      user: { name: 'tempuser', roles: ['authenticated'] },\n      kill: false,\n    });\n\n    // Now, call drupalSession with kill: true to destroy the session.\n    cy.drupalSession({ kill: true }).then(() => {\n      // Verify logout by checking for a login form or absence of user-specific elements.\n      cy.visit(drupalBaseUrl); // Revisit to ensure the page reflects the new session state\n      cy.get('a[href=\"/user/login\"]').should('be.visible'); // Check for login link\n      cy.get('.toolbar-icon-user').should('not.exist');\n      cy.contains('tempuser').should('not.exist');\n    });\n  });\n});","lang":"typescript","description":"Demonstrates how to include the package in the Cypress support file and provides runnable Cypress tests for logging in and logging out Drupal users using `cy.drupalSession()`."},"warnings":[{"fix":"Ensure the 'Test Session' module is enabled and accessible at the `/test-session` endpoint on your Drupal site. Consult the Drupal Test Session module documentation for setup instructions.","message":"This package is a client for the Drupal Test Session module. The module must be installed and properly configured on your Drupal site for the Cypress commands to function. Without the Drupal module, the commands will fail with backend errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `DRUPAL_BASE_URL` in your `cypress.config.ts` or `cypress.env.json` file, or as a system environment variable prefixed with `CYPRESS_` (e.g., `CYPRESS_DRUPAL_BASE_URL=https://my-drupal.com`).","message":"The `DRUPAL_BASE_URL` environment variable (accessed via `Cypress.env('DRUPAL_BASE_URL')`) must be correctly configured if your Drupal site is not running on `http://localhost:8888`. Incorrect configuration will lead to commands targeting the wrong URL.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `require('drupal-test-session-cypress');` to your primary Cypress support file (e.g., `cypress/support/e2e.ts`).","message":"The package must be `require()`-d in your `cypress/support/index.js` or `cypress/support/e2e.ts` file. If this step is missed, Cypress will report that `cy.drupalSession` is not a function, as the global commands will not have been registered.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include `cy.visit(Cypress.env('DRUPAL_BASE_URL'))` or a specific Drupal page in your `beforeEach` hook before making `cy.drupalSession()` calls.","message":"When using `cy.drupalSession()` within tests, it's often crucial to ensure that Cypress is currently visiting the Drupal site's origin (e.g., `cy.visit(drupalBaseUrl)` in a `beforeEach` hook). Without being on the correct origin, cookie and session management commands might behave unexpectedly or fail due to cross-origin policies.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `require('drupal-test-session-cypress');` to your `cypress/support/index.js` or `cypress/support/e2e.ts` file.","cause":"The `drupal-test-session-cypress` package was not correctly required in the Cypress support file, so its commands were not registered globally.","error":"CypressError: `cy.drupalSession` is not a function."},{"fix":"Define `DRUPAL_BASE_URL` in your `cypress.config.ts/js` (e.g., `env: { DRUPAL_BASE_URL: 'http://my-drupal.local' }`), `cypress.env.json`, or as a system environment variable prefixed with `CYPRESS_` (e.g., `CYPRESS_DRUPAL_BASE_URL=http://my-site.com`).","cause":"The `DRUPAL_BASE_URL` environment variable, which `drupal-test-session-cypress` relies on, has not been set or is empty in the Cypress configuration.","error":"Error: \"DRUPAL_BASE_URL\" is not defined or is empty. Please set the DRUPAL_BASE_URL environment variable."},{"fix":"Verify that the Drupal Test Session module is installed and enabled on your Drupal site. Double-check the `DRUPAL_BASE_URL` in your Cypress configuration to ensure it points to the correct Drupal instance.","cause":"The Drupal Test Session module endpoint (usually `/test-session`) was not found, likely because the module is not installed, not enabled, or the `DRUPAL_BASE_URL` is incorrect.","error":"CypressError: cy.request() failed with status code 404: Not Found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}