doc: testing lambdas #2340

sixhobbits · 2023-07-20T09:35:22Z

Depends on FusionAuth/fusionauth-node-cli#5

Testing lambdas fix formatting

…edit Testing lambdas language first edit

Testing lambdas language edit

mooreds

General feedback:

weird that the TOC is cramped (at least, I saw that--did you?)
first character of each word in a header should be capitalized

mooreds · 2023-08-14T21:11:37Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+## Prerequisites
+
+To follow this guide, you will need a test instance of FusionAuth. For FusionAuth installation instructions, please visit [the 5-minute setup guide](/docs/v1/tech/5-minute-setup-guide). 


prerequisite isn't just a running fusionauth instance, seems like you have to go through the 5 minute guide to get the .js scripts

mooreds · 2023-08-14T21:12:13Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+### Lambda Limitations
+
+{% include _callout-note.liquid content="<p>Remember the following limitations of lambdas when planning what they'll do:<ul><li>Lambdas do not have full access to JavaScript libraries, nor can they load them currently.</li> <li>The console methods take only one argument.</li><li>HTTP requests are not available in the Community or Starter FusionAuth plans.</li><li>If you set the Identity Provider <a href='/docs/v1/tech/identity-providers/#linking-strategies'>linking strategy</a> to 'Link Anonymously', no lambdas will be used for external authentication.</li> </ul></p>"%}


Can you break this out to a separate include file?

Would like to include them in the known limitations section as well.

added the file site/_includes/docs/_lambda-limitations.adoc

site/docs/v1/tech/lambdas/testing-lambdas.md

mooreds · 2023-08-14T21:15:01Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImd0eSI6WyJhdXRob3JpemF0aW9uX2NvZGUiXSwia2lkIjoiMWU1NmM0OWU4In0.eyJhdWQiOiJkZGQwNTAyMS0wNjgyLTQ4NWUtYThlMi1kMDMyOTY0YjAyMTEiLCJleHAiOjE2ODkyNjQwNzEsImlhdCI6MTY4OTI2MDQ3MSwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIwYTkzOTYwNi0zNmVjLTQ1M2ItOTM0Mi04ZWZmOTE3ZjJhZWYiLCJqdGkiOiIyYmZlMjUwNy1hZWM0LTRjOTEtYWY5Yy1hOWVhYjQzNmQ4MGYiLCJhdXRoZW50aWNhdGlvblR5cGUiOiJQQVNTV09SRCIsImVtYWlsIjoiZXJsaWNoQGV4YW1wbGUuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImFwcGxpY2F0aW9uSWQiOiJkZGQwNTAyMS0wNjgyLTQ4NWUtYThlMi1kMDMyOTY0YjAyMTEiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwicm9sZXMiOltdLCJzaWQiOiIzNDk5MTAxMS1kNzUxLTRlOTctYWZiNi0zNzQ2N2RlYTc5YWIiLCJhdXRoX3RpbWUiOjE2ODkyNjA0NzEsInRpZCI6ImNiY2VkOWVhLWQ3NzgtZDBlYi03ZjU4LWE0MGYxY2VlNWFhYiIsIm1lc3NhZ2UiOiJIZWxsbyBXb3JsZCEifQ.3DOvP8LRAp6pIh0guUjJjYbNwZKzruVWre8Xq8x_S8k
+```
+
+Copy this token from your terminal and paste it into the <span>Encoded</span>{:.field} text box at [jwt.io](https://jwt.io). You'll see `"message": "Hello World!"` in the <span>Payload</span>{:.uielement} box at the bottom right, showing you that your new lambda ran correctly.


Please don't point to jwt.io. Point to the fusionauth jwt decoder.

mooreds · 2023-08-14T21:25:10Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+Make a new file in the app called `test.js` and paste the following code into it.
+
+```js
+const client = require('@fusionauth/typescript-client');


Let's put this in a repo and import it using remote_include, please.

mooreds · 2023-08-14T21:25:43Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+node test.js | npx faucet
+```
+
+In reality, you'll want to create a random user at the beginning of each login test and remove it at the end. This will allow you to add multiple lambda tests while avoiding potential conflicts between test users and permissions.


If this is best practice, why don't we do in the script? That seems reasonable to do.

mooreds · 2023-08-14T21:26:00Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+The next test you'll write is a unit test that verifies your lambda locally using a fake mock service and not in FusionAuth. The benefit of this test is that you can test your logic works without needing an external service to be reliable at the time of testing. The danger is that your test might pass locally, but the lambda might fail on FusionAuth due to it running on a different JavaScript environment with different restrictions and configuration.
+
+Let's take an example where you check if users have email addresses from a country sanctioned by the United States, such as North Korea or Cuba. You call an external site, `https://issanctioned.example.com`, with an email address, and are told whether the domain is banned or not.


Cool example!

site/docs/v1/tech/lambdas/testing-lambdas.md

mooreds · 2023-08-14T21:29:27Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+```
+
+In reality, you'll want to create a random user at the beginning of each login test and remove it at the end. This will allow you to add multiple lambda tests while avoiding potential conflicts between test users and permissions.
+


Would be great to have another unit test example where you are pulling attributes from the user object, performing logic on it, and then setting a value on a jwt. Maybe the user has a certain role ('admin', 'editor', 'viewer') and the JWT is given certain permissions based on those: (admin -> 'all', 'editor' -> 'read', 'write', viewer' -> 'read'). or something similar. But I think this kind of logic is where unit tests shine, plus showing how to mock up a user object would be useful.

Co-authored-by: Dan Moore <dan@fusionauth.io>

…up on including local adoc snippets in md.

# Conflicts: # DocsDevREADME.md

…e-edit Revised Testing Lambdas language edit

rideam · 2023-08-22T12:57:47Z

@mooreds The example repo is here https://github.com/ritza-co/fusionauth-example-testing-lambdas

Depends on FusionAuth/fusionauth-node-cli#8

rideam · 2023-08-22T13:26:06Z

The TOC being cramped seems to have something to do with the file being markdown and not adoc

mooreds · 2023-08-22T13:53:41Z

The TOC being cramped seems to have something to do with the file being markdown and not adoc

Don't worry about it then. Just remove it. Thanks!

mooreds · 2023-08-23T20:57:14Z

site/docs/v1/tech/lambdas/index.adoc

-* `method`, which defaults to `GET`
-* `headers`, which defaults to null
-* `body`, which must be a string
+{% include docs/_lambda-limitations.adoc %}


TODO for Dan: update the lambda section of the limitations doc to include this.

mooreds · 2023-08-23T20:58:26Z

site/docs/v1/tech/lambdas/testing-lambdas.md

@@ -0,0 +1,380 @@
+---


Can you move this file and the images to the guides section and rename this "Lambda Guide"

Because it does more than just testing.

so it should live under https://fusionauth.io/docs/v1/tech/guides/

mooreds · 2023-08-23T21:01:18Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+  }
+```
+
+You can see that the user object has data that the JWT does not, like names, birthdates, and languages, that you might want to add in a lambda.


I'm sorry I was vague here. What I'd love to do is see someone able to:

download their lambda via the node CLI

run a unit test against that lambda where the test code is outside of the directory, but the downloaded lambda is being tested

have the user and other objects mocked up by the test

Does that make sense? What you provided is helpful, but the user will still have to copy and paste their lambda code into test.js every time it is downloaded.

Can we import the lambda function into the test context?

mooreds · 2023-08-23T21:03:20Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+Although you can use the [lambda API](/docs/v1/tech/apis/lambdas) directly by making HTTP requests, it's much easier to use one of the provided [client libraries](/docs/v1/tech/client-libraries/).
+
+There are two libraries for Javascript:


Suggested change

There are two libraries for Javascript:

There are two ways to do this using Javascript:

mooreds · 2023-08-23T21:04:14Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImd0eSI6WyJhdXRob3JpemF0aW9uX2NvZGUiXSwia2lkIjoiMWU1NmM0OWU4In0.eyJhdWQiOiJkZGQwNTAyMS0wNjgyLTQ4NWUtYThlMi1kMDMyOTY0YjAyMTEiLCJleHAiOjE2ODkyNjQwNzEsImlhdCI6MTY4OTI2MDQ3MSwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIwYTkzOTYwNi0zNmVjLTQ1M2ItOTM0Mi04ZWZmOTE3ZjJhZWYiLCJqdGkiOiIyYmZlMjUwNy1hZWM0LTRjOTEtYWY5Yy1hOWVhYjQzNmQ4MGYiLCJhdXRoZW50aWNhdGlvblR5cGUiOiJQQVNTV09SRCIsImVtYWlsIjoiZXJsaWNoQGV4YW1wbGUuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImFwcGxpY2F0aW9uSWQiOiJkZGQwNTAyMS0wNjgyLTQ4NWUtYThlMi1kMDMyOTY0YjAyMTEiLCJzY29wZSI6Im9mZmxpbmVfYWNjZXNzIiwicm9sZXMiOltdLCJzaWQiOiIzNDk5MTAxMS1kNzUxLTRlOTctYWZiNi0zNzQ2N2RlYTc5YWIiLCJhdXRoX3RpbWUiOjE2ODkyNjA0NzEsInRpZCI6ImNiY2VkOWVhLWQ3NzgtZDBlYi03ZjU4LWE0MGYxY2VlNWFhYiIsIm1lc3NhZ2UiOiJIZWxsbyBXb3JsZCEifQ.3DOvP8LRAp6pIh0guUjJjYbNwZKzruVWre8Xq8x_S8k
+```
+
+Copy this token from your terminal and paste it into the <span>Token</span>{:.field} text box on the [FusionAuth Online JWT Decoder](https://fusionauth.io/dev-tools/jwt-decoder). You'll see `"message": "Hello World!"` in the <span>Payload</span>{:.uielement} box, showing you that your new lambda ran correctly.


Suggested change

Copy this token from your terminal and paste it into the Token{:.field} text box on the [FusionAuth Online JWT Decoder](https://fusionauth.io/dev-tools/jwt-decoder). You'll see `"message": "Hello World!"` in the Payload{:.uielement} box, showing you that your new lambda ran correctly.

Copy this token from your terminal and paste it into the Token{:.field} text box on the [FusionAuth Online JWT Decoder](/dev-tools/jwt-decoder). You'll see `"message": "Hello World!"` in the Payload{:.uielement} box, showing you that your new lambda ran correctly.

Please remove all absolute URL references to fusionauth.io.

mooreds · 2023-08-23T21:27:59Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+Add this new function to `test.js`. 
+
+```js
+{% remote_include 'https://raw.githubusercontent.com/FusionAuth/fusionauth-example-testing-lambdas/main/complete-application/documentation_snippets/test_3.js' %}


I don't understand the point of putting this into a documentation snippet? The point of pulling this from a remote server is that the code will be runnable and stay up to date. See for example the doc here: https://fusionauth.io/docs/v1/tech/themes/client-side-password-rule-validation

How does putting these into a documentation snippet help with this goal?

How about instead you build up a test suite that the user can run?

mooreds · 2023-08-23T21:31:49Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+node test.js
+```
+
+In FusionAuth, click on <span>Users</span>{:.breadcrumb} to check that a new user called `lambdatestuser` has been created. You can delete the `createRandomUser(uuidv4());` line in `test.js` as each test will use a new temporary user. This will allow you to add multiple lambda tests while avoiding potential conflicts between test users and permissions.


why did we call createRandomUser here just to delete it? Is this proving that the typescript library is configured correctly or for some other reason?

mooreds · 2023-08-23T21:33:19Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+Now you will test that the lambda returns "Goodbye World", which will confirm that the CLI `update` command worked.
+
+Add this code to the `test.js` file.


Can you have multiple test files using the NPM test library? Looks like it: tape tests/**/*.js

Then you could have each file live for real separately in the repo, rather than have users keep adding to test.js

mooreds · 2023-08-23T21:34:50Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+The second object is the user supplied to your `populate()` function in a lambda.
+
+```js
+user: {


Please pull these from https://github.com/FusionAuth/fusionauth-site/tree/master/site/docs/src/json as those json files will be updated over time.

mooreds · 2023-08-23T21:35:52Z

site/docs/v1/tech/lambdas/testing-lambdas.md

+
+```bash
+node test.js  | npx faucet
+```


Can we see sample output of the tests (all three)? No need for a screenshot, just copying and pasting the output is fine.

…s too.

Lambda Guide language edit

vcampitelli · 2023-12-04T15:03:56Z

I've migrated this guide to MDX and am closing this in favor of #2705

* 📝 refs 2340 Migrating "Testing Lambdas" to MDX * 📝 refs #2340 Renaming "Testing Lambdas" * 📝 refs #2705 Fixing description in the "Testing Lambdas" guide * 🔨 refs #2705 Add missing JSON to the Lambda testing guide * 📝 refs #2705 Few touch-ups to the Lambda Testing guide after review * 📝 refs #2705 Removing comments from actual code and moving to the paragraph before

rideam and others added 11 commits July 14, 2023 11:31

testing lambdas

3369ff5

update images

22bc130

update images

b96dd83

Testing lambdas language first edit

57f77cb

Testing lambdas fix formatting

8300f43

Merge pull request #107 from ritza-co/testing-lambdas-fix-formatting

6020240

Testing lambdas fix formatting

Merge pull request #106 from ritza-co/testing-lambdas-language-first-…

59528fa

…edit Testing lambdas language first edit

add toc

c7d93ea

format limitations

ef1e844

Testing lambdas language edit

763ce9c

Merge pull request #108 from ritza-co/testing-lambdas-language-edit

929d0bf

Testing lambdas language edit

sixhobbits requested a review from mooreds July 20, 2023 09:36

mooreds added the content Alert marketing to this change label Jul 26, 2023

mooreds requested changes Aug 14, 2023

View reviewed changes

sixhobbits and others added 15 commits August 15, 2023 10:14

Apply suggestions from code review

0c37be0

Co-authored-by: Dan Moore <dan@fusionauth.io>

Titlecase headings

7025cf1

Moving lambda limitations into its own include file

4ec789d

Using external code snippets

eca331e

Using temporary users in the new repo

d941820

Remove unusual line terminators from docsreadme file

ad9e90b

Added new unit test for roles and permissions

2601ef5

Given up trying to get remote tag includes to work in .md. And given …

69d177b

…up on including local adoc snippets in md.

Make todo when moving to Astro

14d0832

Add another todo for Astro

225c429

Added description of linking and unlinking lambdas to applications

4e5b41a

Merge branch 'master' into testing-lambdas

6da9b01

# Conflicts: # DocsDevREADME.md

text updates

6617215

Revised Testing Lambdas language edit

836aea2

Merge pull request #126 from ritza-co/revised-testing-lambdas-languag…

83502a8

…e-edit Revised Testing Lambdas language edit

rideam requested a review from mooreds August 22, 2023 13:06

fix json snippet tag causing text to render in red

4d78e18

remove TOC

eea2f9b

mooreds requested changes Aug 23, 2023

View reviewed changes

RichardJECooke and others added 11 commits September 5, 2023 09:49

Remove link and unlink lambdas from node cli

720fb1c

"There are two ways to do this using Javascript"

36d0544

Remove fusionauth.io absolute links

a7621a2

Moved JWt and User properties to JSON files in /docs/src/json

4eb6908

Moved lambda article from customizations-testing to guides. And image…

c6db7c8

…s too.

Converted tests 1 and 2 to separate files

6ff1b37

Add section explaining how to run all tests

32f181c

Finished article.

bb72170

Use eval to run tests

727bdb0

Making security warning less dramatic

54d3da4

include fixes and text updates

f5e7bff

rideam mentioned this pull request Sep 8, 2023

Restructure the Lambda testing code FusionAuth/fusionauth-example-testing-lambdas#1

Merged

rideam and others added 3 commits September 8, 2023 18:26

text updates

0a9a955

Lambda Guide language edit

a3f7d02

Merge pull request #133 from ritza-co/lambda-guide-language-edit

88ff125

Lambda Guide language edit

sixhobbits requested a review from mooreds September 15, 2023 14:40

vcampitelli self-requested a review November 21, 2023 22:36

vcampitelli added a commit that referenced this pull request Dec 4, 2023

📝 refs #2340 Renaming "Testing Lambdas"

b7a3e68

vcampitelli mentioned this pull request Dec 4, 2023

Migrating "Testing Lambdas" to MDX #2705

Merged

vcampitelli closed this Dec 4, 2023


		## Prerequisites

		To follow this guide, you will need a test instance of FusionAuth. For FusionAuth installation instructions, please visit [the 5-minute setup guide](/docs/v1/tech/5-minute-setup-guide).


		### Lambda Limitations

		{% include _callout-note.liquid content="<p>Remember the following limitations of lambdas when planning what they'll do:<ul><li>Lambdas do not have full access to JavaScript libraries, nor can they load them currently.</li> <li>The console methods take only one argument.</li><li>HTTP requests are not available in the Community or Starter FusionAuth plans.</li><li>If you set the Identity Provider <a href='/docs/v1/tech/identity-providers/#linking-strategies'>linking strategy</a> to 'Link Anonymously', no lambdas will be used for external authentication.</li> </ul></p>"%}


		The next test you'll write is a unit test that verifies your lambda locally using a fake mock service and not in FusionAuth. The benefit of this test is that you can test your logic works without needing an external service to be reliable at the time of testing. The danger is that your test might pass locally, but the lambda might fail on FusionAuth due to it running on a different JavaScript environment with different restrictions and configuration.

		Let's take an example where you check if users have email addresses from a country sanctioned by the United States, such as North Korea or Cuba. You call an external site, `https://issanctioned.example.com`, with an email address, and are told whether the domain is banned or not.

		```

		In reality, you'll want to create a random user at the beginning of each login test and remove it at the end. This will allow you to add multiple lambda tests while avoiding potential conflicts between test users and permissions.


		Although you can use the [lambda API](/docs/v1/tech/apis/lambdas) directly by making HTTP requests, it's much easier to use one of the provided [client libraries](/docs/v1/tech/client-libraries/).

		There are two libraries for Javascript:

	There are two libraries for Javascript:
	There are two ways to do this using Javascript:

	Copy this token from your terminal and paste it into the <span>Token</span>{:.field} text box on the [FusionAuth Online JWT Decoder](https://fusionauth.io/dev-tools/jwt-decoder). You'll see `"message": "Hello World!"` in the <span>Payload</span>{:.uielement} box, showing you that your new lambda ran correctly.
	Copy this token from your terminal and paste it into the <span>Token</span>{:.field} text box on the [FusionAuth Online JWT Decoder](/dev-tools/jwt-decoder). You'll see `"message": "Hello World!"` in the <span>Payload</span>{:.uielement} box, showing you that your new lambda ran correctly.


		Now you will test that the lambda returns "Goodbye World", which will confirm that the CLI `update` command worked.

		Add this code to the `test.js` file.

doc: testing lambdas #2340

doc: testing lambdas #2340

Uh oh!

Conversation

sixhobbits commented Jul 20, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mooreds left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rideam commented Aug 22, 2023

Uh oh!

rideam commented Aug 22, 2023

Uh oh!

mooreds commented Aug 22, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vcampitelli commented Dec 4, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sixhobbits commented Jul 20, 2023 •

edited

Loading