Skip to content

libraries.md

Latest commit

 

History

History
262 lines (203 loc) · 13.8 KB

libraries.md

File metadata and controls

262 lines (203 loc) · 13.8 KB
Raw

gas-fakes logo Using Google Apps Script Libraries with gas-fakes

gas-fakes provides robust support for testing your Google Apps Script projects that use shared libraries. This allows you to develop and test your code locally, even when it has complex dependencies, by simulating the Apps Script library environment.

There are three primary ways to make your libraries available in the gas-fakes environment:

  1. Automatic Loading: From your project's appsscript.json manifest.
  2. Custom Manifest: By providing a manifest object directly in your code.
  3. Manual Loading: From the command line interface (CLI).

1. Automatic Library Loading from Manifest

If your project already has an appsscript.json file with libraries listed in the dependencies section, gas-fakes can automatically load them. This is the most seamless method as it uses your existing project configuration.

How it Works

gas-fakes provides a global object, LibHandlerApp, in the execution environment. To load the libraries from your project's manifest, simply call LibHandlerApp.load(). It's best practice to wrap this call in a check for ScriptApp.isFake, so your code doesn't produce errors when running on Google's actual servers.

The load() method will:

  1. Read your appsscript.json manifest file.
  2. Find all the libraries listed in the dependencies.libraries array.
  3. Fetch the code for each library.
  4. Recursively perform the same process for any libraries that your dependencies use.
  5. "Inject" all the libraries into the global scope, making them available for your script to use.

Example

Let's say your appsscript.json looks like this:

{
  "timeZone": "Europe/London",
  "dependencies": {
    "libraries": [{
      "userSymbol": "TestLib",
      "libraryId": "1zOlHMOpO89vqLPe5XpC-wzA9r5yaBkWt_qFjKqFNsIZtNJ-iUjBYDt-x",
      "version": "1"
    }]
  }
}

Your script main.js can then load and use the library:

// main.js

// Best practice: Only run this in the gas-fakes environment
if (typeof ScriptApp !== 'undefined' && ScriptApp.isFake) {
  // Load all libraries from the project manifest
  LibHandlerApp.load();
}

function myFunction() {
  // Now you can use functions from TestLib
  TestLib.hello();
}

myFunction();

You can run this with gas-fakes, and it will automatically fetch and include TestLib:

npx gas-fakes -f main.js

2. Providing a Custom Manifest

You can also pass a manifest object directly to LibHandlerApp.load(). This is useful for testing specific library configurations without modifying your project's appsscript.json.

Example

Here's an example of loading a library using a custom-defined manifest object.

// test-script.js

// Best practice: Only run this in the gas-fakes environment
if (typeof ScriptApp !== 'undefined' && ScriptApp.isFake) {
  const mockManifest = {
    dependencies: {
      libraries: [
        {
          libraryId: '13JUFGY18RHfjjuKmIRRfvmGlCYrEkEtN6uUm-iLUcxOUFRJD-WBX-tkR',
          userSymbol: 'bmPreFiddler',
        },
      ],
    },
  };
  LibHandlerApp.load(mockManifest);
}

function runFiddler() {
  // Use the library loaded from the mock manifest
  const result = bmPreFiddler.PreFiddler().getFiddler({id:'xxx', sheetName:"yyy"}).getData();
  console.log(result.slice(0, 5));
}

runFiddler();

3. Manual Library Loading from the CLI

For quick tests or situations where you don't want to create a manifest, you can manually specify libraries using the --libraries flag with the gas-fakes CLI.

How it Works

The --libraries flag takes an argument in the format Identifier@Source.

  • Identifier: This is the name your script will use to refer to the library (e.g., MyLib).
  • Source: This is where to get the library code. It can be:
    • A path to a local JavaScript file (e.g., ./libs/my-lib.js).
    • A URL pointing to a raw JavaScript file.
    • The script ID of a deployed Google Apps Script library.

You can provide the --libraries flag multiple times to load multiple libraries.

Example

Imagine you have a local library file sample-lib.js:

// sample-lib.js
function sayHello() {
  console.log('Hello from the library!');
}

And a script main.js that wants to use it:

// main.js
function runTest() {
  // MyLib is available because we are loading it via the CLI
  MyLib.sayHello();
}

runTest();

You can run your main script and link the library using this command:

npx gas-fakes -f main.js --libraries "MyLib@sample-lib.js"

The output would be: Hello from the library!

Gas-Fakes Progress Summary

Service Classes Methods Completed In Progress Not Started
Base 17 127 93 2 32
Cache 2 11 7 4 0
Calendar 13 273 273 0 0
Charts 29 238 37 0 201
Content 3 16 16 0 0
Document 47 1032 880 12 140
Drive 8 164 124 8 32
Forms 41 504 266 0 238
Gmail 6 168 167 0 1
HTML 6 39 34 0 5
JDBC 20 753 311 0 442
Lock 2 7 7 0 0
Mail 1 5 0 0 5
Properties 4 11 6 5 0
Script 16 84 22 0 62
Slides 76 1288 1005 0 283
Spreadsheet 108 1771 1301 19 451
URL Fetch 2 13 12 0 1
Utilities 5 59 59 0 0
XML 14 149 142 0 7
Total 420 6712 4762 50 1900

gas-fakes logo Further Reading

Watch the gas-fakes intro video

Watch the intro video

Watch the explainer about delegating work to local LLMs to save token costs

Use local LLMs to save tokens

Watch the gf_agent video on natural language automation

Use natural language with gf_agent

Watch the local webapps and addons development video

Local Apps Script Webapp and UI Emulation with gas-fakes

Read more docs