Allow jest-playwright settings in jest.config.js

[jhildenbiddle]

Is your feature request related to a problem? Please describe.

While not a critical issue, allowing jest-playwright settings to live inside of the standard jest.config.js file would simplify the configuration (fewer config files) and make it easier to understand how Jest is configured by allowing more (hopefully, all) settings to live in one place.

As a real-world example, I am currently working on an open-source project that uses jest-playwright for e2e tests but only Jest for unit and integration tests. You can view the work-in-progress implementation here:

• https://github.com/docsifyjs/docsify/tree/jest-playwright/tests

I'm using Jest's projects option to unify configurations for all test types. Because jest-playwright's config exists in a separate file that only applies to a single test type (e2e), I've moved jest-playwright.config.js into the /tests/e2e/config/ folder, which means my Jest configuration is now split between /jest.config.js and /tests/e2e/config/jest-playwright.config.js. Everything works as expected, but understanding the overall test setup is more difficult for new contributors because configuration files are scattered throughout the project.

Describe the solution you'd like

Allow jest-playwright settings live in jest.config.js using a "jest-playwright" property name:

// jest.config.js
module.exports = {
  'jest-playwright': {
    browsers: [
      'chromium',
      'firefox',
      'webkit',
    ]
  }
};

Jest-playwright settings should also be allowed to live under a camelCase jestPlaywright property name. This format is consistent with Jest's property name convention:

// jest.config.js
module.exports = {
  jestPlaywright: {
    // ...
  }
};

The configuration should also work for those using Jest's projects option. Hopefully this will "just work" because of how Jest operates, but I wanted to mention it since Jest projects provide an easy way to isolate jest-playwright to e2e tests.

// jest.config.js
module.exports = {
  projects: [
    // Unit Tests (Jest)
    {
      displayName: 'unit',
      testMatch: ['<rootDir>/tests/unit/*.test.js'],
    },
    // Integration Tests (Jest)
    {
      displayName: 'integration',
      testMatch: ['<rootDir>/tests/integration/*.test.js'],
    },
    // E2E Tests (Jest + Playwright)
    {
      displayName: 'e2e',
      testMatch: ['<rootDir>/tests/e2e/*.test.js'],
      preset: 'jest-playwright-preset',
      jestPlaywright': {
        browsers: [
          'chromium',
          'firefox',
          'webkit',
        ]
      }
    }
  ]
};

(Note above that I personally prefer the camelCase jestPlaywright property name for consistency).

[mmarkelov]

@jhildenbiddle thank you for your suggestion. Looks interesting and useful. Not sure that it will be easy to implement, but I take it after #216

[mmarkelov]

Just made some research on it. Seems like that jest doesn't pass any custom values defined it your jest.config and throw a warning.

As a workaround I passed some options, but only inside globals. So it will be ok:

// jest.config
module.exports = {
    ...,
    preset: "jest-playwright-preset",
    globals: {
        jestPlaywright: {
           ...
        }
    }
}

Also IDK what we should do if we defined some options in jest.config and also in jest-playwright.config

[jhildenbiddle]

Just made some research on it. Seems like that jest doesn't pass any custom values defined it your jest.config and throw a warning.

Interesting. I'm surprised Jest is so strict about unknown properties in the config, but I suppose it's necessary to provide the kind of warnings shown in your screenshot.

I wonder if there's a way for Jest plugin/preset/etc. authors to whitelist new config properties that they want to make available in file jest.config.js file. If this isn't available now, perhaps this is something the Jest team would consider. A simple implementation could just allow devs to add their properties (in this case, "jest-playwright" and jestPlayright) to a global array that Jest checks before warning about unknown options.

someArrayCheckedByJest: [
  'jestPlaywright',
  'someOtherJestAddon'
];
``

Storing property names in an array would suppress the warnings, but it wouldn't provide any assistance to end users when needed as Jest does with its own config properties. To resolve this, a more robust implementation would allow devs to provide messages of different types, each with their own condition(s) that would determine if/when to display them:

```js
someObjectCheckedByJest: {
  jestPlaywright: {
    name: 'jest-playwright',
    description: 'A Jest preset that simplifies running tests with Playwright',
    url: 'https://github.com/playwright-community/jest-playwright',
    messages: [
      { 
        type: 'info', 
        message: 'Info message', 
        test(jestConfig) { 
          /* Code that returns true when condition is met */ 
        } 
      },
      { 
        type: 'warning', 
        message: 'Warning message', 
        test(jestConfig) { 
          /* Code that returns true when condition is met */ 
        } 
      },
      { 
        type: 'error', 
        message: 'Error message', 
        test(jestConfig) { 
          /* Code that returns true when condition is met */ 
        } 
      }
    ]
  },
  someOtherJestAddon: {
    name: 'Some other Jest Addon',
    description: 'This is some other add-on for Jest',
    url: 'https://github.com/username/repo',
    messages: [
      // ...
    ]
  }
}

If this sounds interesting, I'd be happy to file the issue / feature request in the main Jest repo.

As a workaround I passed some options, but only inside globals.

Seems like a good workaround for now. Personally, I'd prefer to not add globals unless absolutely necessary, but this is better than nothing.

Also IDK what we should do if we defined some options in jest.config and also in jest-playwright.config

I'd do whatever Jest does when configurations are provided in both packages.json and jest.config.js. The Jest docs aren't clear on what happens if configurations are found in both files. Does one take precedence? Are multiple configurations merged? If they're merged, in what order?

[jhildenbiddle]

FWIW, if you're interested in pursuing custom properties in jest.config.js without having to use globals as described above, I'd wait to resolve the issue with the Jest team before releasing support for jest-playwright configs via globals: { jestPlayWright: { /* ... */ }. Probably seems obvious, but I thought it may be worth mentioning.

[mmarkelov]

I wonder if there's a way for Jest plugin/preset/etc. authors to whitelist new config properties that they want to make available in file jest.config.js file.

As I know there is no ability to customize config with new config properties.

If this sounds interesting, I'd be happy to file the issue / feature request in the main Jest repo.

I think that it has sense. Maybe core jest team can help with it.

Personally, I'd prefer to not add globals unless absolutely necessary, but this is better than nothing.

We can wait for an answer from jest about ability to support new config properties. I suppose that I won't be able to make it this week. And there is #216 that I want to implement before this. So maybe it's better to wait for a better solution, instead of using global object

I'd do whatever Jest does when configurations are provided in both packages.json and jest.config.js.

OK. That's reasonable to make it in Jest style.

Does one take precedence? Are multiple configurations merged? If they're merged, in what order?

I need to check it

[mmarkelov]

Also I found that ts-jest for example use global property to pass config with jest.config.js:

// jest.config.js:

module.exports = {
 ...,
  globals: {
    'ts-jest': {
      ...,
    },
  },
};

[jhildenbiddle]

Very interesting. I wonder if that was the guidance from the Jest team, if the TypeScript team opted to do that to make configuration data available globally, or if they were in the same "we want just use jest.config.js for our settings, but it looks like using globals is the only way to do that" situation.

[jhildenbiddle]

@mmarkelov --

What about leveraging Jest's testEnvironmentOptions option? The documentation states the following:

Test environment options that will be passed to the testEnvironment. The relevant options depend on the environment. For example you can override options given to jsdom such as {userAgent: "Agent/007"}.

Perhaps I'm misunderstanding the difference between "environment" and "preset", but my understanding is that when Jest is configured with preset: jest-playwright-preset, jest-playwright-preset is the environment. If this is the case, then it seems like jest-playwright options could be passed in jest.config.js as follows:

// jest.config.js
module.exports = {
  preset: 'jest-playwright-preset',
  testEnvironmentOptions: {
    // jest-playwright options here...
    browsers: [
      'chromium',
      'firefox',
      'webkit',
    ]
  }
};

[mmarkelov]

@jhildenbiddle I need to check it out. I'm not sure that it will help, cause we also need to pass config to PlaywrightRunner

[mmarkelov]

@jhildenbiddle just added this ability with #282
You can do something like that:

// jest.config.js
testEnvironmentOptions: {
        ...,
        'jest-playwright': {
            ...
        }
},

[jhildenbiddle]

@mmarkelov --

Tested and working great on v1.3.1. Much cleaner (IMHO). Thanks!