Unverified Commit 20c1079e authored by Ryan "Haticus" Huellen's avatar Ryan "Haticus" Huellen Committed by GitHub

Clarification for Testing Environment Variables (#38359)

## Documentation / Examples

- [X] Make sure the linting passes by running `pnpm lint`
- [X] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)

## The Issue
When it came to testing environment variables with jest in the current release of NextJS, I ran into an issue where my variables were seemingly undefined for no reason. With some research and the help from a friend in discussion post #38353 it was determined further configuration steps were needed in relation to the environment variables for jest. At the time being, no direct link is made between [Setting up Jest](https://nextjs.org/docs/testing#setting-up-jest-with-the-rust-compiler) and [Test Environment Variables](https://nextjs.org/docs/basic-features/environment-variables#test-environment-variables).

## The Change
This fix provides further clarification on the issue by creating a new link within the note on the [Setting up Jest](https://nextjs.org/docs/basic-features/environment-variables#test-environment-variables) page. Moreover, further explanations were added to ensure developers understand the `test` environment is completely separate from both `development` and `production` meaning files like `.env.development` and `env.prodution` won't be recognized when testing.

## Supporting Documentation
This is an issue time and time again for developers. Not only have I experienced this, but others have asked on both [GitHub Discussions](https://github.com/vercel/next.js/discussions/16270) and [StackOverflow](https://stackoverflow.com/questions/63934104/environment-variables-undefined-in-nextjs-when-running-jest/67997819#67997819). Moreover, many of the solutions from 2020 no longer work properly.

I hope this is sufficient enough for a contribution to the documentation. Minor improvements like these create the ideal developer experience Next.js is known for. :)
Co-authored-by: 's avatarLee Robinson <9113740+leerob@users.noreply.github.com>
parent 085085eb
...@@ -142,7 +142,7 @@ When using the Vercel CLI to deploy make sure you add a [`.vercelignore`](https: ...@@ -142,7 +142,7 @@ When using the Vercel CLI to deploy make sure you add a [`.vercelignore`](https:
## Test Environment Variables ## Test Environment Variables
Apart from `development` and `production` environments, there is a 3rd option available: `test`. In the same way you can set defaults for development or production environments, you can do the same with a `.env.test` file for the `testing` environment (though this one is not as common as the previous two). Apart from `development` and `production` environments, there is a 3rd option available: `test`. In the same way you can set defaults for development or production environments, you can do the same with a `.env.test` file for the `testing` environment (though this one is not as common as the previous two). Next.js will not load environment variables from `.env.development` or `.env.production` in the `testing` environment.
This one is useful when running tests with tools like `jest` or `cypress` where you need to set specific environment vars only for testing purposes. Test default values will be loaded if `NODE_ENV` is set to `test`, though you usually don't need to do this manually as testing tools will address it for you. This one is useful when running tests with tools like `jest` or `cypress` where you need to set specific environment vars only for testing purposes. Test default values will be loaded if `NODE_ENV` is set to `test`, though you usually don't need to do this manually as testing tools will address it for you.
......
...@@ -302,6 +302,8 @@ Under the hood, `next/jest` is automatically configuring Jest for you, including ...@@ -302,6 +302,8 @@ Under the hood, `next/jest` is automatically configuring Jest for you, including
- Ignoring `.next` from test resolving - Ignoring `.next` from test resolving
- Loading `next.config.js` for flags that enable SWC transforms - Loading `next.config.js` for flags that enable SWC transforms
> **Note**: To test environment variables directly, load them manually in a separate setup script or in your `jest.config.js` file. For more information, please see [Test Environment Variables](https://nextjs.org/docs/basic-features/environment-variables#test-environment-variables).
### Setting up Jest (with Babel) ### Setting up Jest (with Babel)
If you opt-out of the [Rust Compiler](https://nextjs.org/docs/advanced-features/compiler), you will need to manually configure Jest and install `babel-jest` and `identity-obj-proxy` in addition to the packages above. If you opt-out of the [Rust Compiler](https://nextjs.org/docs/advanced-features/compiler), you will need to manually configure Jest and install `babel-jest` and `identity-obj-proxy` in addition to the packages above.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment